Outbound Calls

The Outbound Calls feature allows your bot to initiate phone calls to external phone numbers programmatically. This enables use cases such as appointment reminders, notifications, surveys, and proactive customer outreach.

Overview

The outbound calling system works in two main steps:

1. Configuration: Set up your outbound call settings in the phone channel configuration
2. API Integration: Use the REST API to initiate and monitor outbound calls

Prerequisites

Before using the outbound calls feature, ensure you have:

• A bot with a configured phone channel
• Access to the phone channel configuration (Channel Manager role required)
• API credentials with appropriate permissions

---

Step 1: Configure Outbound Call Settings

Navigate to your bot's phone channel settings and configure the outbound call parameters.

Configuration Parameters

1. Enable Outbound Calls

Toggle the "Enable outbound calls" option to activate the feature.

2. Display Name (Optional)

• Description: The name that will be displayed to the call recipient
• Example: "Company Inc.", "Customer Service"
• Note: This may or may not be displayed depending on the recipient's phone system and the SIP providers policy

3. Display Number (Required)

• Description: The phone number that will be displayed to the call recipient
• Format: International format recommended (e.g., +4912345678)
• Note: There may be restrictions or requirements regarding the Display Number depending on the SIP providers policy

4. Outgoing Line (Required)

• Description: The SIP trunk or line configuration for outbound calls
• Example: "Outbound_Trunk"
• Note: This should be configured by your phone system administrator

Saving Configuration

After configuring all required fields, click Save to apply the outbound call settings.

---

Step 2: Generate an API Key

To make outbound call requests, you need an API key with the appropriate permissions.

Creating the API Key

Refer to the API Keys documentation for detailed instructions on creating an API key with the following required settings:

• Scope: Read and Write permissions
• Roles: Channel Manager role

Important: Copy the API key immediately after creation as it will only be displayed once.

---

Step 3: Initiate an Outbound Call

Use the REST API to create an outbound call request.

API Endpoint

POST /bots/{botId}/phone-outbound-calls

Request Headers

x-api-key: {your-api-key}
Content-Type: application/json

Request Body

{
    "targetNumber": "+49123456789",
    "timeout": 30,
    "metadata": {
        "campaignId": "summer-2024",
        "customerId": "CUST-12345"
    },
    "sipHeader": {
        "X-Custom-Header": "value"
    }
}

Request Parameters

Parameter	Type	Required	Description
targetNumber	string	Yes	The phone number to call (international format recommended)
timeout	number	No	Maximum ringing duration in seconds before the call is cancelled if not answered (default: 30)
metadata	object	No	Custom metadata to attach to the call. Given metadata will be set as value of the slot sys_phone_session_start_metadata
sipHeader	object	No	Custom SIP headers to include in the call. These headers will be transmitted as part of the SIP INVITE message to the recipient

Response

A successful request returns a call document with the following structure:

{
    "_id": "507f1f77bcf86cd799439011",
    "botId": "507f191e810c19729de860ea",
    "tenantId": "507f191e810c19729de860eb",
    "targetNumber": "+49123456789",
    "callId": "1701234567890-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "initialized",
    "timeout": 30,
    "metadata": {
        "campaignId": "summer-2024",
        "customerId": "CUST-12345"
    },
    "sipHeader": {
        "X-Custom-Header": "value"
    },
    "createdAt": "2024-12-05T10:30:00.000Z",
    "updatedAt": "2024-12-05T10:30:00.000Z"
}

Call ID

The callId field is a unique identifier for the call, formatted as: {timestamp}-{uuid}

Save this callId to monitor the call status later.

Example Request (cURL)

curl -X POST https://your-instance.com/bots/507f191e810c19729de860ea/phone-outbound-calls \
  -H "x-api-key: 507f1f77bcf86cd799439011.a3b2c1d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "targetNumber": "+49123456789",
    "timeout": 30,
    "metadata": {
      "campaignId": "summer-2024",
      "customerId": "CUST-12345"
    }
  }'

---

Step 4: Monitor Call Status

After initiating a call, you can query its status using the call ID.

API Endpoint

GET /bots/{botId}/phone-outbound-calls/{callId}

Request Headers

x-api-key: {your-api-key}

Response

{
    "_id": "507f1f77bcf86cd799439011",
    "botId": "507f191e810c19729de860ea",
    "tenantId": "507f191e810c19729de860eb",
    "targetNumber": "+49123456789",
    "callId": "1701234567890-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "in_call",
    "statusDetails": "Call answered by recipient",
    "timeout": 30,
    "metadata": {
        "campaignId": "summer-2024",
        "customerId": "CUST-12345"
    },
    "sipHeader": {
        "X-Custom-Header": "value"
    },
    "createdAt": "2024-12-05T10:30:00.000Z",
    "updatedAt": "2024-12-05T10:30:45.000Z"
}

Call Status Values

The status field indicates the current state of the call:

Status	Description
initialized	The call has been created and is being prepared for dialing
queued	The call is queued and will be dialed shortly
dialing	The call is being dialed
ringing	The call is ringing on the recipient's end
in_call	The call was anwered and is currently in progress
completed	The call has been completed successfully
failed	The call has failed to connect. See statusDetails for more information
no_answer	The call was not answered by the recipient
rejected	The call was rejected by the recipient
busy	The recipient's line is busy

Example Request (cURL)

curl -X GET https://your-instance.com/bots/507f191e810c19729de860ea/phone-outbound-calls/1701234567890-a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-api-key: 507f1f77bcf86cd799439011.a3b2c1d4-e5f6-7890-abcd-ef1234567890"

---

Metadata on Call Failure

If the call does not reach in_call (i.e. it ends up as failed, no_answer, rejected, or busy), four additional fields are merged into the metadata object before it is passed on to the bot conversation as sys_phone_session_start_metadata. This lets a flow react to a failed outbound call (e.g. trigger a fallback/retry) even though no conversation with the recipient ever took place.

This also applies when the call fails before dialing even starts (e.g. an invalid outgoing line): the POST /phone-outbound-calls request itself returns an HTTP 500 response, but a bot conversation is started in parallel with outbound_call_failed set in the metadata, so a flow reading sys_phone_session_start_metadata still executes even though the API call failed.

Field	Type	Description
outbound_call_failed	boolean	Always true when this metadata is present — indicates the call did not connect
outbound_call_status	string	The resulting call status, one of failed, no_answer, rejected, busy (see Call Status Values)
outbound_call_cause	number or null	The raw SIP/telephony hangup cause code reported by the phone system (may be 0 for no-answer calls — 0 is a valid cause code, not "unset"). null only if the call never reached the point of dialing (e.g. a configuration error)
outbound_call_error	string or null	A human-readable error message, only set if the call failed before dialing (e.g. invalid outgoing line). null for normal call-progress failures (busy/no answer/rejected), where outbound_call_cause is set instead

---

Error Handling

Common Error Responses

401 Unauthorized

{
    "statusCode": 401,
    "message": "Invalid API Key"
}

Solution: Verify your API key is correct and has not expired.

403 Forbidden

{
    "statusCode": 403,
    "message": "Forbidden. Required roles: channel-manager"
}

Solution: Ensure your API key has the Channel Manager role and Write scope.

404 Not Found

{
    "statusCode": 404,
    "message": "Call not found"
}

Solution: Verify the callId and botId are correct.

500 Internal Server Error

{
    "error": "Failed to initiate outbound call for call_id: <call_id>."
}

This is returned when the call could not be dialed at all (e.g. an invalid or misconfigured outgoing line). Note that a bot conversation is started regardless, with outbound_call_failed metadata injected — see Metadata on Call Failure — so a flow can still react to the failure even though the API response itself is a 500.

Solution: Verify the configured outbound line and check the error detail in the logs.

---

Troubleshooting

Calls Not Initiating

Possible Causes:

1. Outbound calls not enabled in phone channel configuration
2. Missing or incorrect outgoing line configuration
3. Invalid display number
4. API key lacks required permissions

Solutions:

1. Verify all configuration fields are properly set
2. Check phone system logs for connection issues
3. Ensure API key has Channel Manager role and Write scope

Calls Failing Immediately

Possible Causes:

1. Invalid target phone number format
2. Blocked number or prefix
3. Insufficient phone system capacity
4. Network connectivity issues

Solutions:

1. Validate phone number format
2. Check blocked numbers list in phone channel settings
3. Contact your phone system administrator
4. Verify phone server connectivity