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.

Creating a V2 agent via API

Follow these steps to create a V2 agent using the SynthFlow API. The process involves two main steps:

1. Creating a custom phone number
2. Creating the agent and linking it to the phone number

1. Create a Custom Phone Number

Endpoint:
POST /v2/custom-numbers

Headers:

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

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 fields.

2. Create a V2 agent

This call creates a V2 agent and binds it to the previously created phone number.

Make sure the phone number is created before calling this endpoint.

Endpoint:
POST /v2/agents

Headers:

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

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"   // Important
13
}

See API documentation for other possible fields

Final Step: Configure Twilio

Once the trunk is ready on SynthFlow, redirect Twilio calls to it using TwiML commands.

Javascript Example:

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

Python Example:

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