Direct connection to the Twin voice bot is a type of integration where calls are routed directly to the bot, bypassing the Twin Call System. This type of integration can be useful for companies with their own customized phone system, featuring specific logic and high capacity. If you do not have your own telephony system or use PBX providers’ services, this type of integration cannot be implemented.
¶ Benefits of Direct Integration
- Maximum integration of the bot into the telephone infrastructure.
- Supports a high call volume (over 40–50 concurrent calls) handled by the bot.
- Full control over the call flow on the client side.
- Preparation of dialogue sessions with variables necessary for the bot to operate without additional requests to the server from the script.
¶ Platform Limitations
- When handling calls, the Twin system operates with a CPS limit. CPS (calls per second) is the number of calls a company can initiate per second. If a company attempts to initiate more calls than allowed, the call will be rejected by the system.
- The connection is established exclusively through a built tunnel (L2TP, PPTP, IPSec, L2, etc.).
¶ General workflow
¶ Handling Calls with Direct Integration
To send a call to the bot, follow these three steps:
- Log in to the system (once at a specified interval).
- Warm up the call.
- Send a call to the bot via the SIP protocol.
¶ Authorization in the system
To get started, log in to the Twin system and obtain a JWT token. Information on the authorization API is available in the IAM service documentation.
¶ Call warm-up
Call warm-up is a notification to the Twin system about an upcoming connection with the bot. Warm-up involves sending an HTTP request containing information about the call or batch of calls that will soon be forwarded to the bot via the SIP protocol.
The session lifetime is 3 minutes.
cURL of a warm-up request:
curl --location 'https://cis.twin24.ai/api/v1/calls' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
"returnAnswerAsync": false,
"calls": [
{
"clientExternalId": "CLIENT_EXTERNAL_ID",
"callId": "CLIENT_CALL_ID",
"callerId": "**********",
"number": "**********",
"botSettingsId": "BOT_ID",
"variables": {
"variable_name1": "variable_value1",
"variable_name2": "variable_value2"
},
"callback": [
{
"url": "URL",
"data": {
"key1": "key2"
}
}
]
}
]
}'
| Parameter | Value |
|---|---|
| returnAnswerAsync | Warm-up mode: synchronous (false) and asynchronous (true). In synchronous warm-up, the response from the server will arrive after the warm-up is complete, indicating that the bot is ready to receive a call. In asynchronous mode, the response is returned immediately, and the warm-up occurs in the background. |
| CLIENT_EXTERNAL_ID | Client identifier in the customer’s system. This parameter can be used to retrieve all calls associated with the client from the analytics service. The business meaning of this parameter is uniqueness within the context of a person/lead/deal (depending on the type of the customer’s system). |
| CLIENT_CALL_ID | Call ID in the customer’s system – a representation of the call being made in the customer’s system. This parameter is returned in the response to the request. |
| callerId | The caller’s phone number. |
| number | The recipient’s phone number. |
| variables | A set of variables for the bot’s script. |
| botSettingsId | The ID of the bot script that will initiate the conversation with the user. |
| callback | An array of addresses to be notified of the result of the conversation with the bot. Each element consists of two fields: URL and DATA. The data passed in DATA is not accessible to the bot and is returned to the webhook unchanged. |
Answer example:
{
"CLIENT_CALL_ID1": "a3b30a28-cf89-4fe1-be2d-aabfb9d691bb",
"CLIENT_CALL_ID2": "a3b30a28-cf89-4fe1-be2d-aabfb9d691bc",
}
The values for CLIENT_CALL_ID1 are taken from the callId field of the calls array.
Please note:
If you receive null instead of an identifier, it means the call warm-up request has been rejected. Do not attempt to dial the subscriber. The system is not ready to accept a call on the specified line.
If this endpoint does not respond with a 200 status code, it means the Twin system is not ready to accept calls. Temporarily stop dialing and try again in a few minutes.
¶ Sending a Call to the Bot via SIP
After the client has answered the call and the warm-up is complete, send the call to the bot at the address provided by Twin’s staff.
The following headers must be included in the INVITE to establish a connection:
- X-TWIN-Access=ROBOT_SESSION_UUID (from step 2)
- X-TWIN-TransferMethod=refer
- X-RobotVer=2
If you need to enable call recording, additionally send the header X-TWIN-EnableRecord=1
When recording on the Twin side, only the portion of the conversation with the robot will be recorded. The entire dialogue before the transfer to the robot and after the transfer from the robot to the operator will not be included in the recording.
¶ Recommendations for working with direct integration
- It is recommended to configure the PBX so that the warm-up begins immediately upon receiving a call from a customer. Until the warm-up is complete, do not send an Answer (SIP code 200) to the customer, as this may delay the start of the conversation for the duration of the warm-up.
- Swap the callerId and number for dial-in systems. If your system is the one initiating the call, send the number you are calling to in callerId, and the number you are calling from in number. This will allow you to retrieve the phone number you called in the script for potential decision-making. This swap is necessary because, with direct integration, the Twin system treats all calls as incoming, and the subscriber’s number is taken from callerId.
- Do not ignore the warm-up response. If you did not receive an identifier during warm-up, do not initiate the dialing process for the subscriber—such a call will not be successful. If you did not receive a 200 status code when requesting a warm-up, temporarily stop the dialing process and try again in a few minutes.
- Use asynchronous mode only for outbound dialing. If a call is routed to a robot via SIP before the session warm-up procedure is complete, the system will reject the call. Keep in mind that warming up a call takes an average of 1 second.
- Do not warm up sessions if you do not intend to call the customer in the near future.
The session lifetime is 3 minutes. If more time elapses between the session warm-up request and the actual establishment of a connection with the user, such a call to the bot will be rejected.