Skip to main content
POST
/
calls
/
make-call
cURL
curl --request POST \
  --url https://api.callab.ai/v1/calls/make-call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ai_agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "call_from": "<string>",
  "call_to": "<string>",
  "dynamic_variables": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "workspace": "<string>"
}
'
{
  "status": "<string>",
  "message": "<string>",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "call_sid": "<string>",
    "company_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "ai_agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "call_provider": "<string>",
    "call_from": "<string>",
    "call_to": "<string>",
    "call_duration": 123,
    "call_status": "<string>",
    "call_direction": "<string>",
    "is_test": true,
    "call_rating": 123,
    "cost": 123,
    "price_unit": "<string>",
    "latency": 123,
    "disconnect_reason": "<string>",
    "analysis_sentiment": "<string>",
    "agent_task_status": "<string>",
    "agent_task_feedback": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "workspace_id": "<string>",
    "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "call_feedback": "<string>",
    "record_url": "<string>",
    "transcript": "<string>",
    "transcript_object": {},
    "transcript_language": "<string>",
    "metadata": {},
    "agent_dynamic_variables": {},
    "agent_post_call_outcomes": {},
    "notes": "<string>",
    "deleted_at": "2023-11-07T05:31:56Z",
    "started_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "retry_at": "2023-11-07T05:31:56Z"
  }
}

​
Make A Call

This endpoint initiates a test call using the specified AI agent and phone numbers.

​
Endpoint Details

  • URL: /v1/calls/make-call
  • Method: POST
  • Authentication: Required (API KEY or JWT Token)
  • Source: src/api/public_apis_v1/call/test_call/test_call_controller.rs

​
Request Headers

HeaderValueDescription
AuthorizationBearer <api_key>Your API KEY or JWT Token

​
Body Details

FieldTypeDescriptionExample
ai_agent_idString (UUID format)The unique identifier for the AI agent initiating the call."550e8400-e29b-41d4-a716-446655440000"
call_fromStringThe phone number to call from. Supports various formats including E.164 and national formats."+1234567890" or "(123) 456-7890"
call_toStringThe phone number to call. Supports various formats including E.164 and national formats."+9876543210" or "987-654-3210"
dynamic_variablesArray of Objects (optional)A list of name-value pairs representing dynamic variables that can influence the behavior of the call.[{"name": "customer_name", "value": "John"}]
workspaceString (optional)The workspace identifier. Defaults to “default” if not provided."production" or "staging"

​
Validation Rules

​
Phone Number Formats

Both call_from and call_to accept various phone number formats:
  • E.164 format: +1234567890
  • National formats: (123) 456-7890, 123-456-7890
  • With dots: 123.456.7890
  • With spaces: 123 456 7890
  • With extensions: 1234567890 ext 123
  • International with separators: +1 (123) 456-7890

​
Dynamic Variables

  • Variable names must not be empty
  • Variable names cannot contain spaces
  • Variable values must not be empty

​
Workspace

  • If provided, must not be empty
  • Maximum length: 100 characters

​
Example Request

curl -X POST https://api.callab.ai/v1/calls/make-call \
-H "Authorization: Bearer <api_key>" \
-H "Content-Type: application/json" \
-d '{
  "ai_agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "call_from": "+1234567890",
  "call_to": "+9876543210",
  "dynamic_variables": [
    {
      "name": "customer_name",
      "value": "John Doe"
    },
    {
      "name": "appointment_time",
      "value": "3:00 PM"
    }
  ],
  "workspace": "production"
}'

​
Response

​
Success Response

  • Status Code: 200 OK
{
  "status": "ok",
  "message": "ok",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "call_sid": "CALL_abc123def456",
    "campaign_id": null,
    "ai_agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "contact_id": null,
    "company_id": "550e8400-e29b-41d4-a716-446655440001",
    "call_from": "+1234567890",
    "call_to": "+9876543210",
    "call_duration": 0,
    "call_status": "pstn-queued",
    "call_direction": "outgoing",
    "call_provider": "clusterlab_twilio",
    "call_rating": 0,
    "call_feedback": null,
    "record_url": null,
    "transcript": null,
    "is_test": true,
    "transcript_object": null,
    "transcript_language": null,
    "cost": 0.0,
    "price_unit": "USD",
    "latency": 0,
    "disconnect_reason": "",
    "analysis_sentiment": "",
    "agent_task_status": "",
    "agent_task_feedback": "",
    "metadata": null,
    "agent_dynamic_variables": [
      {
        "name": "customer_name",
        "value": "John Doe"
      },
      {
        "name": "appointment_time",
        "value": "3:00 PM"
      }
    ],
    "agent_post_call_outcomes": null,
    "notes": null,
    "created_at": "2023-10-01T12:00:00Z",
    "updated_at": "2023-10-01T12:00:00Z",
    "deleted_at": null,
    "started_at": null,
    "ended_at": null,
    "retry_at": null,
    "workspace_id": "production"
  }
}

​
Error Responses

​
Validation Error

  • Status Code: 400 Bad Request
When validation fails, the server responds with detailed information about which fields failed validation. 
{
  "status": "error",
  "message": "Validation failed",
  "data": [
    {
      "field": "call_from",
      "message": "Invalid phone number format"
    },
    {
      "field": "dynamic_variables[0].name",
      "message": "Variable name cannot contain spaces"
    }
  ]
}

​
Service Error

  • Status Code: 400 Bad Request
When the service fails to make the call (e.g., phone number not found, AI agent not found): 
{
  "status": "error",
  "message": "error",
  "data": ""
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Test call configuration data

Data required to make a test call

​
ai_agent_id
string<uuid>
required

The unique identifier for the AI agent initiating the call

​
call_from
string
required

The phone number to call from. Supports various formats including E.164 and national formats

​
call_to
string
required

The phone number to call. Supports various formats including E.164 and national formats

​
dynamic_variables
object[] | null

A list of name-value pairs representing dynamic variables that can influence the behavior of the call

​
workspace
string | null

The workspace identifier. Defaults to 'default' if not provided

Response

Test call initiated successfully

​
status
string
required

Status of the response (ok)

​
message
string
required

Response message

​
data
object
required

Detailed information about a call.