Dial API - Outbound Call

Initiate an outbound call via PBX

Overview

This endpoint initiates an outbound phone call through the PBX system associated with the given robot.

Authentication

All requests must include an API token in the Authorization header using HTTP Token authentication:

Authorization: Token token=your_api_key

Endpoint

POST /api/v1/robots/{robot_id}/dial

Request Format

Headers

Header	Value	Required
`Authorization`	`Token token=your_api_key`	Yes
`Content-Type`	`application/json`	Yes

URL Parameters

Parameter	Type	Required	Description
`robot_id`	Integer	Yes	The ID of the robot with configured PBX connection

Request Body

Field	Type	Required	Description
`extension`	String	Yes	Caller agent extension number on the PBX (e.g. `"1001"`)
`target`	String	Yes	Target phone number to dial (e.g. `"+421900000000"`)

Example Request

{
  "extension": "1001",
  "target": "+421900000000"
}

Response

200 OK: Call session created successfully. Returns the PBX session object.

{
  "id": "session_abc123",
  "caller": "1001",
  "callee": "+421900000000",
  "status": "ringing"
}

400 Bad Request:

Missing required parameter (extension or target)
PBX API returned an error (invalid extension, authentication failure, unreachable number, etc.). The response body contains the error details from the PBX:

// String error:
{
  "error": "Invalid extension number"
}

// Array of errors (from PBX):
{
  "error": [
    {
      "code": "invalid_extension",
      "message": "Extension not found",
      "detail": "Extension 1001 does not exist on this tenant"
    }
  ]
}

Common PBX errors include:

401 Unauthorized - Invalid PBX credentials configured on the robot
403 Forbidden - Extension not permitted to make outbound calls
404 Not Found - Extension does not exist on the PBX
422 Unprocessable Entity - Invalid call parameters
Connection error - PBX server is unreachable

401 Unauthorized: Missing or invalid API token.

404 Not Found: Robot with the given ID does not exist or does not belong to the authenticated user.

Example

cURL

curl -X POST https://admin.jarabot.com/api/v1/robots/42/dial \
  -H "Authorization: Token token=your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "extension": "1001",
    "target": "+421900000000"
  }'

Last updated: