> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tabbly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Call

> Trigger a voice agent call programmatically to a user's phone number

<ApiMethod method="post" path="/trigger-call">
  Trigger a voice agent call to a specified phone number. The agent will call the destination number and engage in a conversation based on the agent's configuration and any custom instructions provided.
</ApiMethod>

## Request

<ParamField body="organization_id" type="integer" required>
  Your organization ID
</ParamField>

<ParamField body="use_agent_id" type="integer" required>
  The ID of the agent to use for the call
</ParamField>

<ParamField body="called_to" type="string" required>
  Destination phone number in E.164 format (e.g., +917359043943)
</ParamField>

<ParamField body="call_from" type="string" required>
  Source phone number in E.164 format. Must be registered in your agents\_phone\_numbers
</ParamField>

<ParamField body="custom_first_line" type="string" required>
  The initial message the agent will say when the call connects
</ParamField>

<ParamField body="custom_instruction" type="string">
  Dynamic user-specific context to be combined with the base prompt. Use this to provide personalized information for the call.
</ParamField>

<ParamField body="called_by_account" type="string" default="API">
  Identifier for who/what triggered the call. Default value should be "API"
</ParamField>

<ParamField body="api_key" type="string" required>
  Your organization API key
</ParamField>

<ParamField body="custom_identifiers" type="string" required>
  Any user\_id, uuid, or unique identifier that you want to pass for mapping the record back to your system. Pass empty string "" if no identifier available.
</ParamField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  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": "+917359056097",
      "call_from": "+14156801215",
      "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": "user_12345"
  }'
  ```

  ```python Python theme={null}
  import requests
  import json

  data = {
      'organization_id': 244,
      'use_agent_id': 33,
      'called_to': '+917359056097',
      'call_from': '+14156801215',
      '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': 'user_12345'
  }

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

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const data = {
      organization_id: 244,
      use_agent_id: 33,
      called_to: '+917359056097',
      call_from: '+14156801215',
      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: 'user_12345'
  };

  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));
  ```

  ```php PHP theme={null}
  $data = [
      'organization_id' => 244,
      'use_agent_id' => 33,
      'called_to' => '+917359056097',
      'call_from' => '+14156801215',
      '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' => 'user_12345'
  ];

  $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);

  echo $response;
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the call was successfully triggered
</ResponseField>

<ResponseField name="sip_trunk_id" type="string">
  SIP trunk identifier for the call
</ResponseField>

<ResponseField name="sip_call_to" type="string">
  SIP destination for the call
</ResponseField>

<ResponseField name="room_name" type="string">
  Room name for the call session
</ResponseField>

<ResponseField name="participant_identity" type="string">
  Participant identity in the call
</ResponseField>

<ResponseField name="participant_name" type="string">
  Participant name in the call
</ResponseField>

### Success Response (200 OK)

```json theme={null}
{
    "success": true,
    "sip_trunk_id": "string",
    "sip_call_to": "string",
    "room_name": "string",
    "participant_identity": "string",
    "participant_name": "string"
}
```

## Error Responses

<ResponseField name="400" type="object">
  Missing required fields
</ResponseField>

<ResponseField name="402" type="object">
  Insufficient wallet balance. Minimum balance of 0.2 required to initiate calls.
</ResponseField>

<ResponseField name="404" type="object">
  Organization/Agent not found or invalid call\_from number
</ResponseField>

<ResponseField name="500" type="object">
  Server error
</ResponseField>

## Important Notes

<Warning>
  All phone numbers must be in E.164 format (+\[country code]\[number])
</Warning>

<Warning>
  The call\_from number must be registered in your agents phone numbers database in your Tabbly account
</Warning>

<Warning>
  Minimum wallet balance of 0.2 required to initiate calls
</Warning>

<Note>
  Custom first line should be a clear, concise message the agent will start with. Keep it under 50 words for best results.
</Note>

<Note>
  Use custom\_instruction to provide context-specific information that will be combined with the agent's base prompt. This allows for personalized conversations.
</Note>