Sign in
latestOpenAPI 3.1.0MITraw.githubusercontent.com2026-08-142528921.8 MB

a884f7dcbfc3

AI Webhooks

Amazon Bedrock SWAIG tool webhook

Sent to a tool's web_hook_url (or the SWAIG defaults.web_hook_url) when an amazon_bedrock agent calls one of your functions. Your endpoint runs the function and replies with a JSON object. Both fields are optional, so {} is a valid reply:

  • response — the result the agent reads next. A plain string only here; the {tool_result, tool_prompt} object form that ai agents accept is not read. Omit it and the agent reads a default result.
  • action — a single action object or an array of them, executed on the live call.

There is no post_process: a Bedrock agent always defers actions until after it has spoken.

Bedrock agents send a different payload from ai agents. Notably content_type is text/json rather than text/swaig, argument carries no substituted value, there is no version, description, or argument_desc, and the call's timing and caller fields are named differently. Write your handler against this payload, not the AI SWAIG tool webhook.

postWebhookbedrockSwaigToolWebhook

Payload

functionstring required

The name of the function the agent is calling.

call_idstring required

The ID of the call.

ai_session_idstring required

The ID of the AI session on the call. Matches call_id for Bedrock agents.

app_namestring required

The name of your Bedrock application. Defaults to bedrock.

caller_idstring required

The caller's number. An empty string when the call has none.

global_dataobject required

The agent's current global_data. Alongside anything you seeded, the session adds caller_id_name and caller_id_number when the call carries them.

content_typestring required

The content type of the request body. Always text/json.

content_dispositionstring required

How the body is delivered. Always agent.function for a function call.

conversation_typestring required

The kind of conversation the agent is running. Always voice.

actionstring required

What the request is asking of you. Always fetch_conversation for a function call; the end-of-call conversation report sends post_conversation instead.

project_idstring

Your project ID, when available.

space_idstring

Your Space ID, when available.

conversation_idstring

The conversation ID, when the agent was configured with one.

caller_id_namestring

The caller's name, when available.

caller_id_numberstring

The caller's number, when available.

call_start_dateinteger

When the call was created, as a Unix timestamp in microseconds.

call_answer_dateinteger

When the call was answered, as a Unix timestamp in microseconds. 0 when it never was.

call_end_dateinteger

When the call ended, as a Unix timestamp in microseconds. 0 while the call is still up.

ai_start_dateinteger

When the agent started, as a Unix timestamp in microseconds.

ai_end_dateinteger

When the agent stopped, as a Unix timestamp in microseconds. Omitted while it is still running.

SWMLVarsobject

SWML variables for the call. Included when the call carries SWML state.

SWMLCallobject

SWML call state. Included when the call carries SWML state.

meta_data_tokenstring required

The token that scopes meta_data. This is the meta_data_token you set on the function, or an MD5 of the function's name when you did not set one.

meta_dataobject required

Metadata scoped to meta_data_token. An empty object when the function has none yet.

Example payload

{
  "function": "get_weather",
  "argument": {
    "parsed": [
      {
        "city": "San Francisco"
      }
    ],
    "raw": "{\"city\":\"San Francisco\"}"
  },
  "call_id": "2e1e66e5-5d07-413d-9668-55542992eec0",
  "ai_session_id": "2e1e66e5-5d07-413d-9668-55542992eec0",
  "app_name": "bedrock",
  "caller_id": "+15555550100",
  "global_data": {
    "customer_tier": "premium",
    "pickup_address": "123 Main St, Springfield"
  },
  "content_type": "text/json",
  "content_disposition": "agent.function",
  "conversation_type": "voice",
  "action": "fetch_conversation",
  "project_id": "4d0d6f16-5881-4fcc-92a4-02c51a91954d",
  "space_id": "451ed9ff-e568-4222-8af9-4f9ab7428d09",
  "caller_id_name": "Jane Doe",
  "caller_id_number": "+15555550100",
  "times": [
    {
      "response": "Your ride is booked for 6pm.",
      "response_word_count": 6,
      "answer_time": 1.42,
      "token_time": 0.31,
      "tokens": 53,
      "avg_tps": 37.3,
      "tps": 41.2
    }
  ],
  "meta_data_token": "d742c5d1d969d9fdbbd9bd1c52499f2d",
  "meta_data": {
    "order_number": "12345"
  }
}

Response

Webhook received