Create Batch Outbound Calls

API Endpoint

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

Request Headers

required

Bearer your-api-key

required

application/json

Request Body

string

required

The ID of the outbound agent to use for all calls in the batch.

array

required

List of calls to queue. Minimum 1, maximum 100 per request. Each item must include phoneNumber and optionally promptVariables and metadata.

string

required

The phone number to call (e.g., "966501234567"). Must match your SIP trunk’s outbound format.

object

Dynamic variables injected into the agent’s prompt for this specific call. Key-value pairs of strings.

object

Arbitrary metadata attached to this call. Not passed to the agent prompt.

Example Request

{
  "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
  "calls": [
    {
      "phoneNumber": "966501234567",
      "promptVariables": {
        "customer_name": "Ahmed Al-Rashid",
        "appointment_date": "Wednesday, October 8, 2025",
        "appointment_time": "3:00 PM"
      }
    },
    {
      "phoneNumber": "966509876543",
      "promptVariables": {
        "customer_name": "Sara Al-Otaibi",
        "appointment_date": "Thursday, October 9, 2025",
        "appointment_time": "11:00 AM"
      }
    },
    {
      "phoneNumber": "966551112233",
      "promptVariables": {
        "customer_name": "Khalid Al-Harbi",
        "appointment_date": "Friday, October 10, 2025",
        "appointment_time": "1:00 PM"
      }
    }
  ]
}

Response

boolean

required

true if at least one call was queued successfully.

object

required

The duplicate handling policy applied to this batch.

string

required

DEDUPE — duplicate phone numbers within the same request are dropped. SPACED — duplicates are allowed but spaced 10 minutes apart.

number

required

Minutes between duplicate calls when mode is SPACED. Always 10.

object

required

Counts for the outcome of each call in the batch.

number

required

Total number of calls received in the request.

number

required

Calls queued for immediate dialing.

number

required

Calls queued with a future scheduled time (only applies in SPACED mode for duplicates).

number

required

Calls dropped because the same phone number already appeared earlier in the request (only in DEDUPE mode).

number

required

Calls that failed validation or hit a rate limit.

array

required

Per-call outcome list. One entry per call in the original request.

string

required

The phone number from the original request.

string

required

One of: queued_now, queued_later, failed, deduped.

string

ISO timestamp of when the call will be dialed. Only present when action is queued_later.

string

Failure or dedup reason. Only present when action is failed or deduped.

string

required

Webhook ID for tracking this batch’s call events.

string

required

The agent ID used for the batch.

number

required

Total calls received (same as summary.received).

number

required

Total calls successfully queued (queuedNow + queuedLater).

number

required

Total calls that failed.

number

required

Number of duplicate phone numbers removed in DEDUPE mode.

Example Response

{
  "success": true,
  "data": {
    "policy": {
      "mode": "DEDUPE",
      "spacingMinutes": 10
    },
    "summary": {
      "received": 3,
      "queuedNow": 3,
      "queuedLater": 0,
      "deduped": 0,
      "failed": 0
    },
    "items": [
      { "phoneNumber": "966501234567", "action": "queued_now" },
      { "phoneNumber": "966509876543", "action": "queued_now" },
      { "phoneNumber": "966551112233", "action": "queued_now" }
    ],
    "webhookId": "webhook_xyz789",
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
    "total": 3,
    "queued": 3,
    "failed": 0,
    "duplicatesRemoved": 0
  }
}

Duplicate Handling

The duplicate policy is configured per company in the dashboard. The default is DEDUPE. DEDUPE (default): If the same phone number appears more than once in a single request, only the first occurrence is queued. The rest are dropped with action: "deduped". SPACED: All occurrences are queued but spaced 10 minutes apart. Later duplicates will have action: "queued_later" with a scheduledFor timestamp.

Error Handling

string

Top-level error message when the entire request fails (e.g., agent not found, missing SIP trunk).

Per-call failures are returned in data.items with action: "failed" and a reason field — they do not cause the whole request to fail.

Common Errors

"phoneNumber" or "calls" must be provided, not both — do not mix single-call and batch fields in the same request
promptVariables/metadata must be per-call for batch requests — top-level promptVariables is not allowed for batch; put them inside each call item
Agent not found / not configured — agent must be an outbound agent with a SIP trunk
Contact rate limit — a phone number was called too recently; data.items[].reason will include the reset time

Example Partial Failure Response

{
  "success": true,
  "data": {
    "policy": { "mode": "DEDUPE", "spacingMinutes": 10 },
    "summary": {
      "received": 3,
      "queuedNow": 2,
      "queuedLater": 0,
      "deduped": 0,
      "failed": 1
    },
    "items": [
      { "phoneNumber": "966501234567", "action": "queued_now" },
      { "phoneNumber": "966509876543", "action": "failed", "reason": "Contact rate limit exceeded. Resets at 2025-10-08T15:00:00Z" },
      { "phoneNumber": "966551112233", "action": "queued_now" }
    ],
    "webhookId": "webhook_xyz789",
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
    "total": 3,
    "queued": 2,
    "failed": 1,
    "duplicatesRemoved": 0
  }
}

curl -X POST "https://app.sawt.sa/api/v1/calls/outbound" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
    "calls": [
      {
        "phoneNumber": "966501234567",
        "promptVariables": {
          "customer_name": "Ahmed Al-Rashid",
          "appointment_date": "Wednesday, October 8, 2025",
          "appointment_time": "3:00 PM"
        }
      },
      {
        "phoneNumber": "966509876543",
        "promptVariables": {
          "customer_name": "Sara Al-Otaibi",
          "appointment_date": "Thursday, October 9, 2025",
          "appointment_time": "11:00 AM"
        }
      },
      {
        "phoneNumber": "966551112233",
        "promptVariables": {
          "customer_name": "Khalid Al-Harbi",
          "appointment_date": "Friday, October 10, 2025",
          "appointment_time": "1:00 PM"
        }
      }
    ]
  }'

const axios = require("axios");

const createBatchCalls = async () => {
  try {
    const response = await axios.post(
      "https://app.sawt.sa/api/v1/calls/outbound",
      {
        agentId: "e63355c6-cf51-40f3-b006-b615d9ab762d",
        calls: [
          {
            phoneNumber: "966501234567",
            promptVariables: {
              customer_name: "Ahmed Al-Rashid",
              appointment_date: "Wednesday, October 8, 2025",
              appointment_time: "3:00 PM",
            },
          },
          {
            phoneNumber: "966509876543",
            promptVariables: {
              customer_name: "Sara Al-Otaibi",
              appointment_date: "Thursday, October 9, 2025",
              appointment_time: "11:00 AM",
            },
          },
          {
            phoneNumber: "966551112233",
            promptVariables: {
              customer_name: "Khalid Al-Harbi",
              appointment_date: "Friday, October 10, 2025",
              appointment_time: "1:00 PM",
            },
          },
        ],
      },
      {
        headers: {
          Authorization: "Bearer your-api-key",
          "Content-Type": "application/json",
        },
      }
    );

    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error(error);
  }
};

createBatchCalls();

import requests

def create_batch_calls():
    url = "https://app.sawt.sa/api/v1/calls/outbound"

    headers = {
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json"
    }

    data = {
        "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
        "calls": [
            {
                "phoneNumber": "966501234567",
                "promptVariables": {
                    "customer_name": "Ahmed Al-Rashid",
                    "appointment_date": "Wednesday, October 8, 2025",
                    "appointment_time": "3:00 PM"
                }
            },
            {
                "phoneNumber": "966509876543",
                "promptVariables": {
                    "customer_name": "Sara Al-Otaibi",
                    "appointment_date": "Thursday, October 9, 2025",
                    "appointment_time": "11:00 AM"
                }
            },
            {
                "phoneNumber": "966551112233",
                "promptVariables": {
                    "customer_name": "Khalid Al-Harbi",
                    "appointment_date": "Friday, October 10, 2025",
                    "appointment_time": "1:00 PM"
                }
            }
        ]
    }

    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

result = create_batch_calls()
print(result)

Webhooks

Real-time Call Events

Subscribe to webhooks to receive real-time notifications for each call in the batch. All calls in a batch share the same webhookId.

Sawt API Introduction

Voice Call Endpoints

Speech Services

Create Batch Outbound Calls

API Endpoint

Request Headers

Request Body

Response

Duplicate Handling

Error Handling

Common Errors

Webhooks

Real-time Call Events

​API Endpoint

​Request Headers

​Request Body

​Response

​Duplicate Handling

​Error Handling

​Common Errors

​Webhooks

Real-time Call Events

API Endpoint

Request Headers

Request Body

Response

Duplicate Handling

Error Handling

Common Errors

Webhooks