Trigger outbound call

Place an immediate outbound campaign call via project API key

POST /organizations/{organization_id}/projects/{project_id}/campaigns/{campaign_id}/trigger-call

cURL

curl -X POST "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/campaigns/CAMPAIGN_ID/trigger-call" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bot_live_YOUR_KEY" \
  -d '{
    "phone_number": "[phone]",
    "name": "Alex Rivera",
    "order_id": "ORD-1042"
  }'

const response = await fetch(
  `https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/campaigns/${campaignId}/trigger-call`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.BOTCADENCE_API_KEY,
    },
    body: JSON.stringify({
      phone_number: "[phone]",
      name: "Alex Rivera",
      order_id: "ORD-1042",
    }),
  }
);
const result = await response.json();
console.log(result.data.campaign_queue_id);

import os
import requests

response = requests.post(
    f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/campaigns/{campaign_id}/trigger-call",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["BOTCADENCE_API_KEY"],
    },
    json={
        "phone_number": "[phone]",
        "name": "Alex Rivera",
        "order_id": "ORD-1042",
    },
)
response.raise_for_status()
print(response.json()["data"]["campaign_queue_id"])

200

{
  "status": "success",
  "message": "Outbound call successfully queued and dispatched.",
  "data": {
    "success": true,
    "campaign_queue_id": "665f1a2b3c4d5e6f7a8b9c0d",
    "message": "Call initiated to [phone]"
  },
  "status_code": 200
}

{
  "status": "error",
  "message": "phone_number is required.",
  "data": null,
  "status_code": 400
}

{
  "status": "error",
  "message": "Missing API Key. Please provide X-API-Key header.",
  "data": null,
  "status_code": 401
}

Starts a real-time outbound voice call using a campaign configured in the dashboard.

Required scope: calls:create

Prerequisites

• Outbound campaign with workflow (or static script + voice) and caller ID
• Project API key with calls:create for the same organization and project

You do not need a dial list or to start the campaign for API-triggered calls.

Authentication

X-API-Key · string · required

Project API key with the calls:create scope. Format: bot_live_…

See Authentication.

Path parameters

organization_id · string · required

Organization ID. Must match the API key.

project_id · string · required

Project ID. Must match the API key.

campaign_id · string · required

Outbound campaign ID.

Body

Send a JSON object representing the customer. Extra fields are available in prompts as {{ customer.<key> }}.

phone_number · string · required

Destination number. Prefer E.164 (for example [phone]).

name · string

Optional display name ({{ customer.name }}).

email · string

Optional email ({{ customer.email }}).

[custom fields] · string | number | boolean

Any additional keys (for example order_id) are available as {{ customer.order_id }}.

Response

success · boolean · required

true when the call was queued and dispatched.

campaign_queue_id · string · required

Created outbound queue ID.

message · string · required

Human-readable confirmation.

Errors

400 · Bad Request

Missing/invalid body, invalid phone, or campaign not ready.

401 · Unauthorized

Missing, invalid, or revoked API key.

403 · Forbidden

Missing calls:create, or key does not match org/project.

404 · Not Found

Campaign not found.

500 · Internal Server Error

Unexpected dispatch failure.

cURL

curl -X POST "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/campaigns/CAMPAIGN_ID/trigger-call" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bot_live_YOUR_KEY" \
  -d '{
    "phone_number": "[phone]",
    "name": "Alex Rivera",
    "order_id": "ORD-1042"
  }'

const response = await fetch(
  `https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/campaigns/${campaignId}/trigger-call`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.BOTCADENCE_API_KEY,
    },
    body: JSON.stringify({
      phone_number: "[phone]",
      name: "Alex Rivera",
      order_id: "ORD-1042",
    }),
  }
);
const result = await response.json();
console.log(result.data.campaign_queue_id);

import os
import requests

response = requests.post(
    f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/campaigns/{campaign_id}/trigger-call",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["BOTCADENCE_API_KEY"],
    },
    json={
        "phone_number": "[phone]",
        "name": "Alex Rivera",
        "order_id": "ORD-1042",
    },
)
response.raise_for_status()
print(response.json()["data"]["campaign_queue_id"])

200

{
  "status": "success",
  "message": "Outbound call successfully queued and dispatched.",
  "data": {
    "success": true,
    "campaign_queue_id": "665f1a2b3c4d5e6f7a8b9c0d",
    "message": "Call initiated to [phone]"
  },
  "status_code": 200
}

{
  "status": "error",
  "message": "phone_number is required.",
  "data": null,
  "status_code": 400
}

{
  "status": "error",
  "message": "Missing API Key. Please provide X-API-Key header.",
  "data": null,
  "status_code": 401
}