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.

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"
}'

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