Skip to main content
You must have a valid API key to use this endpoint. Make sure the agent is properly configured before making calls.

​
API Endpoint

POST https://app.sawt.sa/api/v1/calls/outbound

​
Request Headers

​
Authorization
required
Bearer your-api-key
​
Content-Type
required
application/json

​
Request Body

​
phoneNumber
string
required
The phone number to call (e.g., “966501234567”). Must match your SIP trunk’s outbound format. You can check the required format on the /phone-number page.
​
agentId
string
required
The ID of the agent you want to make the call. Must be an outbound agent with a configured SIP trunk and phone number. You can verify this configuration on the /phone-number page.
​
promptVariables
object
Optional dynamic variables in key-value pairs that inject into your agent’s prompt
{
  "phoneNumber": "966501234567",
  "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
  "promptVariables": {
    "doctor_name": "Dr. Ahmed",
    "date": "Wednesday, October 8, 2025",
    "time": "Wednesday, October 8, 2025"
  }
}

​
Response

​
success
boolean
required
Whether the call was successfully initiated
​
data
object
required
Call details object containing:
​
data.callTaskId
string
required
Unique task ID for tracking the call
​
data.webhookId
string
required
Webhook ID for receiving call status updates
​
data.phoneNumber
string
required
The phone number that was called
​
data.agentId
string
required
The agent ID used for the call
​
data.companyId
string
required
Your company identifier
​
data.isTest
boolean
required
Whether this is a test call
{
  "success": true,
  "data": {
    "callTaskId": "task_abc123",
    "webhookId": "webhook_xyz789",
    "phoneNumber": "966501234567",
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
    "companyId": "company_123",
    "isTest": false
  }
}

​
Error Handling

​
error
string
Error message if the request fails

​
Common Validation Errors

The following validation errors may occur:
  • Invalid agent type: Agent must be configured for outbound calls (inbound agents are rejected)
  • Missing SIP trunk: Agent must have a SIP trunk and phone number configured (check /phone-number page)
  • Phone number format: Phone number must match your SIP trunk’s outbound format (verify format on /phone-number page)
  • Agent access: Agent must belong to your company (verified via API key)
{
  "error": "Invalid phone number format"
}

{
  "error": "Agent is not configured for outbound calls"
}

{
  "error": "No SIP trunk configured for this agent"
}

{
  "error": "Phone number format does not match SIP trunk configuration"
}

curl -X POST "https://app.sawt.sa/api/v1/calls/outbound" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "phoneNumber": "966501234567",
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
    "promptVariables": {
      "doctor_name": "Dr. Ahmed",
      "date": "Wednesday, October 8, 2025",
      "time": "Wednesday, October 8, 2025"
    }
  }'

​
Webhooks

Real-time Call Events

Subscribe to webhooks to receive real-time notifications about call events, analysis results, and more. Configure your webhooks at app.sawt.sa/webhooks/subscriptions.