Triggering Calls

This page discusses how to trigger voice agent calls programmatically to user's phone number.

Endpoint

POST https://www.tabbly.io/dashboard/agents/endpoints/trigger-call

Headers

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
organization_id	integer	Yes	Your organization ID
use_agent_id	integer	Yes	The ID of the agent to use for the call
called_to	string	Yes	Destination phone number in E.164 format (e.g., [phone])
call_from	string	Yes	Source phone number in E.164 format (must be registered in your agents_phone_numbers)
custom_first_line	string	Yes	The initial message the agent will say
custom_instruction	string	No	Dynamic user specific context to be combined with base prompt
called_by_account	string	No	Default Value should be API
api_key	string	Yes	Your organization API Key here.
custom_identifiers	string	Yes	this refers to any user_id, uuid or any unique identifier that you want to pass for the purpose of mapping the record back to your system. Pass this parameter empty or blank if no available identifier.

Basic cURL Structure

curl -X POST 'https://www.tabbly.io/dashboard/agents/endpoints/trigger-call' \
-H 'Content-Type: application/json' \
-d '{
    "organization_id": 244,
    "use_agent_id": 33,
    "called_to": "[phone]",
    "call_from": "[phone]",
    "custom_first_line": "Hello, I am calling from Company XYZ",
    "custom_instruction": "Vijay's Order ID is 343454X. Order placed on 2nd Jan, 2025.",
    "called_by_account": "test_user",
    "api_key": "your_organization_api_key_here",
    "custom_identifiers": ""
}'

Response Format

Success Response (200 OK)

jsonCopy{
    "success": true,
    "sip_trunk_id": "string",
    "sip_call_to": "string",
    "room_name": "string",
    "participant_identity": "string",
    "participant_name": "string"
}

Error Responses

Status Code	Description
400	Missing required fields
402	Insufficient wallet balance
404	Organization/Agent not found or invalid call_from number
500	Server error

Example Usage

PHP

$data = [
    'organization_id' => 345,
    'use_agent_id' => 583,
    'called_to' => '[phone]',
    'call_from' => '[phone]',
    'custom_first_line' => 'Hello, I am calling from Company XYZ',
    'custom_instruction': 'Vijays Order ID is 343454X. Order placed on 2nd Jan, 2025.',
    'called_by_account' => 'test_user'
];

$ch = curl_init('https://www.tabbly.io/dashboard/agents/endpoints/trigger-call');
curl_setopt_array($ch, [
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json']
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

Python

import requests
import json

data = {
    'organization_id': 3443,
    'use_agent_id': 344,
    'called_to': '[phone]',
    'call_from': '[phone]',
    'custom_first_line': 'Hello, I am calling from Company XYZ',
    'custom_instruction': 'Vijays Order ID is 343454X. Order placed on 2nd Jan, 2025.',
    'called_by_account': 'test_user'
}

response = requests.post(
    'https://www.tabbly.io/dashboard/agents/endpoints/trigger-call',
    json=data,
    headers={'Content-Type': 'application/json'}
)

print(response.json())

Node.js

const axios = require('axios');

const data = {
    organization_id: 244,
    use_agent_id: 33,
    called_to: '[phone]',
    call_from: '[phone]',
    custom_first_line: 'Hello, I am calling from Company XYZ',
    custom_instruction: 'Vijays Order ID is 343454X. Order placed on 2nd Jan, 2025.',
    called_by_account: 'test_user'
};

axios.post('https://www.tabbly.io/dashboard/agents/endpoints/trigger-call', data, {
    headers: { 'Content-Type': 'application/json' }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Important Notes

• All phone numbers must be in E.164 format (+[country code][number])

• The call_from number must be registered in your agents phone numbers database in your tabbly account.

• Minimum wallet balance of 0.2 required to initiate calls

• Custom first line should be a clear, concise message the agent will start with