How to Direct SIP Dialing

In scenarios where your telephony provider does not offer elastic SIP trunking or if you have a more complex telephony setup unsuitable for elastic SIP trunking, you can use direct SIP dialing to our endpoint.

In this scenario, Synthflow does not directly place or receive calls. Rather, your telephony system manages the dialing process to connect with the specified SIP endpoint. You will need to develop the integration logic tailored to your telephony provider’s requirements. From Synthflow’s standpoint, all call interactions will be treated as incoming, so your integration must explicitly define call direction handling.

The process involves three primary steps:

1. Importing a custom phone number
2. Creating the agent and linking it to the phone number
3. Dialing to the SIP Endpoint

API Base URL: https://api.synthflow.ai

Step 1: Import a Custom Phone Number

Endpoint:
POST /v2/custom-numbers

Headers:

1
{
2
  "Content-Type": "application/json",
3
  "Authorization": "Bearer {TOKEN}"
4
}

Request Body:

1
{
2
  "workspace_id": "workspace_id",
3
  "phone_number": "phone_number",
4
  "friendly_name": "Friendly Name",
5
  "trunk_username": "username",         // Optional
6
  "trunk_pwd": "dflkvn23REFD#@"        // Optional
7
}

trunk_username and trunk_pwd are optional and can be omitted unless required for your configuration.

Step 2: Create an agent

This step creates an agent and links it to the custom phone number created in Step 1. Ensure the phone number is successfully created before proceeding.

Endpoint:
POST /v2/agents

Headers:

1
{
2
  "Content-Type": "application/json",
3
  "Authorization": "Bearer {TOKEN}"
4
}

Request Body:

1
{
2
  "type": "inbound",
3
  "agent": {
4
    "llm": "gpt-4o",
5
    "language": "en-US",
6
    "prompt": "hey",
7
    "greeting_message": "hi",
8
    "voice_id": "qTj9lsKOMtF3uVefOvPi"
9
  },
10
  "name": "TestName",
11
  "phone_number": "",
12
  "voice_engine_version": "2.0"
13
}

For additional fields and configurations, refer to the official API documentation.

Step 3: Configure Twilio

After the trunk is set up on SynthFlow, redirect Twilio calls to it using TwiML commands. Be sure to include the GHL unique call ID or Twilio Call SID in the SIP header using the X-EI key.

Javascript Example:

1
const express = require('express');
2
const { twiml: { VoiceResponse } } = require('twilio');
3
4
const app = express();
5
const PORT = process.env.PORT || 3000;
6
const TERMINATION = "sipin.synthflow.ai:32681";
7
8
/**
9
 * Redirects a call to SynthFlow SIP endpoint.
10
 */
11
app.get('/redirect_call', (req, res) => {
12
  const { Called, CallSid } = req.query;
13
  
14
  if (!Called) {
15
    return res.status(400).send('Missing "Called" query parameter');
16
  }
17
18
  const voiceResponse = new VoiceResponse();
19
  voiceResponse.dial().sip(`sip:${Called}@${TERMINATION}?X-EI=${CallSid}`);
20
21
  res.set('Content-Type', 'text/xml');
22
  res.status(200).send(voiceResponse.toString());
23
});
24
25
app.listen(PORT, () => {
26
  console.log(`Server is running on http://localhost:${PORT}`);
27
});

Python Example:

1
from fastapi import FastAPI, Response
2
from twilio.twiml.voice_response import VoiceResponse
3
4
app = FastAPI()
5
TERMINATION = "sipin.synthflow.ai:32681"
6
7
@app.get("/redirect_call")
8
async def redirect_call(Called: str, CallSid: str): # pylint: disable=invalid-name
9
    voice = VoiceResponse()
10
    voice.dial().sip(f"sip:{Called}@{TERMINATION}?X-EI={CallSid}")
11
    return Response(str(voice), media_type="text/xml", status_code=200)

Pre-Actions with Custom Variables

You can use Pre-Actions to fetch custom variables via API and incorporate them into the agent prompt for more personalized responses by using the <twilio_call_sid> verb in API request.

Note: The transfer call will work the same as before.