Configure the SIP Request tool

Before you start, read SIP Request tool for what the tool does, the call requirements, and how to choose a SIP method.

Create the tool

Put everything your receiving system needs in the headers and body. For example, to tell your contact center the caller is verified, send an X-Call-Event header and a body with accountNumber and reason fields.

Fields

For the full schema, see SIP Request tool in the Create Tool API reference.

Tell the assistant when to use it

Add instructions to your system prompt that say when to send the request and what to include. Refer to the tool by the name you gave it. For example:

After the caller confirms their identity, use the send_caller_details tool to send their account number and the reason for their call. Don't tell the caller you are doing this.

Clear field descriptions in your headers and body schemas also help the assistant fill in the right values.

Send a request from an assistant hook

To send a SIP request when a call event happens, instead of when the assistant decides to, run the tool from an assistant hook. For example, this hook sends a timeout-transfer event to your platform after the caller has been silent twice:

{
  "hooks": [
    {
      "on": "customer.speech.timeout",
      "options": {
        "timeoutSeconds": 10,
        "triggerMaxCount": 2
      },
      "do": [
        {
          "type": "tool",
          "tool": {
            "type": "sipRequest",
            "verb": "INFO",
            "headers": {
              "type": "object",
              "properties": {
                "Content-Type": {
                  "type": "string",
                  "default": "application/json"
                }
              }
            },
            "body": {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "default": "timeout-transfer"
                }
              }
            }
          }
        }
      ]
    }
  ]
}

In a hook, header and body fields with a default value are sent as written. Any other field, including the method, is filled in by the assistant from the conversation, so the method warning still applies.

Tool messages

If you don’t configure messages, the assistant says “The request was successful” out loud after the request is sent, and “Sorry, an unexpected error occurred” if it fails.

This tool’s messages all play after the request is sent, not before it. Vapi uses the first one that applies:

1. Request Failed (request-failed), if the request returned an error.
2. Request Start (request-start), if you set one. It plays instead of Request Complete.
3. Request Complete (request-complete).

Because nothing plays before the request, write any Request Start message as something the caller hears afterward, not “Sending that now.”

Most SIP requests are background signals the caller doesn’t need to hear about. To keep the conversation natural, set your own request-complete and request-failed messages. With role set to system, the message content goes to the model as a hint instead of being spoken, and the assistant continues the conversation in its own words:

"messages": [
  {
    "type": "request-complete",
    "role": "system",
    "content": "The details were sent. Continue the conversation without mentioning it."
  },
  {
    "type": "request-failed",
    "role": "system",
    "content": "The details could not be sent. Continue the conversation without mentioning it."
  }
]

For all message options, see SIP Request tool messages in the Create Tool API reference.

Variables

You can use variables such as {{customer.number}} in the header schema, the body (string or schema), and tool messages. Vapi fills them in when the call starts.

For example, this tool sends the call ID, the caller’s number, and a campaign ID in a fixed string body:

{
  "type": "sipRequest",
  "verb": "INFO",
  "body": "call={{call.id}};caller={{customer.number}};campaign={{campaignId}}"
}

The {{call.id}} and {{customer.number}} variables are built in. Pass campaignId in assistantOverrides.variableValues when you start the call.

The SIP Request tool doesn’t support static parameters.

Verify the request was sent

Place a test call over your SIP connection and say whatever should make the assistant send the request. Then check these places:

1. The tool call and its result. In the Dashboard, select Logs, open the call, and select the Messages tab. Find the SIP Request tool call to see the values the assistant generated for the request, and the result that came back. An error result explains why nothing was sent, for example when the call isn’t on Vapi’s SIP transport.
2. The call logs. If the assistant’s Logging setting is enabled, the call’s Logs tab includes a Tool calls finished entry under the Tool category, showing the tool’s result or error.
3. The call’s SIP signaling. For calls on Vapi numbers and BYO SIP trunks, Vapi records a packet capture (PCAP) of the call’s SIP signaling by default. Download it with PCAP on the call’s page, or from artifact.pcapUrl on the call record, and open it in a SIP analysis tool such as Wireshark. See Call recording for the pcapEnabled setting.
4. Your receiving system. A success result in Vapi doesn’t confirm that the other end received or accepted the request. Check the logs on your PBX, SBC, or contact center platform to confirm it received the request and acted on it.

If the request didn’t work:

Related

• SIP Request tool overview
• SIP introduction
• SIP trunking
• Built-in tools
• SIP Request tool in the Create Tool API reference