Route SIP Calls

Your phone system can send a call to a Synthflow agent with a SIP INVITE. Use this when your system, not a SIP trunk, decides which calls reach the agent. To trunk a whole carrier or PBX into Synthflow instead, see Connect over SIP.

Prerequisites

• A custom number assigned to an inbound agent. Synthflow treats every call to that number as inbound.
• Firewall rules for your region’s signaling and media addresses.
• An API key, to hand off a live call or to set up the number through the API.

Send every INVITE to your region’s SIP address on port 32681, listed in SIP addresses. Format the number in E.164, for example sip:+12065551234@sip.us.synthflow.ai:32681.

API setup

You can create the custom number and the agent in the app, or with two API calls.

First, import the number. If your carrier or PBX requires Synthflow to register, set uac_enabled to true and provide trunk_username and trunk_pwd.

Then create an inbound agent on that number. Wait until the number is created before you send this request.

Direct dialing

Send the call to the agent’s number at your region’s SIP address. Synthflow answers it like any other inbound call.

To keep a reference to the call in your own system, add your call ID in the X-EI header. The example below redirects a Twilio call with TwiML and passes the Twilio Call SID.

const express = require('express');
const { twiml: { VoiceResponse } } = require('twilio');
const app = express();
const SYNTHFLOW_SIP = 'sip.us.synthflow.ai:32681';
app.get('/redirect_call', (req, res) => {
  const { Called, CallSid } = req.query;
  if (!Called) {
    return res.status(400).send('Missing "Called" query parameter');
  }
  const response = new VoiceResponse();
  response.dial().sip(`sip:${Called}@${SYNTHFLOW_SIP}?X-EI=${CallSid}`);
  res.type('text/xml').send(response.toString());
});
app.listen(process.env.PORT || 3000);

A before-the-call action can send <twilio_call_sid> to your API, so the agent starts the call with data from your system.

Live call handoff

Your system places or answers the call, runs its own logic, and then transfers the connected call to the agent. Register the call with Synthflow first, so the agent receives your variables and the call keeps one ID.

1. Call registration

Send a POST to /v2/prepare_inbound on your region’s API base URL, with your API key as a bearer token.

curl -X POST https://api.us.synthflow.ai/v2/prepare_inbound \
  -H "Authorization: Bearer $SYNTHFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+14155550199",
    "to_number": "+12065551234",
    "model_id": "your-agent-id",
    "workspace_id": "your-workspace-id",
    "custom_variables": {
      "customer_name": "Jane Doe",
      "account_id": "A12345"
    }
  }'

The response includes two fields you need:

{
  "call_status": "registered",
  "synthflow_call_id": "ebe4bd96-dcb1-4abd-9aa5-686877dab061"
}

• call_status is registered when Synthflow is ready to take the call, and failed during a service outage.
• synthflow_call_id identifies the call. You send it in the next step.

2. SIP transfer

Once the caller is connected, send an INVITE to the agent’s number at your region’s SIP address. Add an X-EI header with the call ID from step 1, in the exact format S.<synthflow_call_id>;, including the trailing semicolon.

The number must be the one assigned to the inbound agent, in E.164 format.

INVITE sip:+12065551234@sip.us.synthflow.ai:32681 SIP/2.0
X-EI: S.ebe4bd96-dcb1-4abd-9aa5-686877dab061;

X-EI can also carry your own call ID and the original caller. See X-EI header for the full format.

Additional context

Any X-* header you add to the INVITE becomes a variable the agent can use in its prompt, actions, and transfers. See Pass call context.