Cancel Queued Call

API Endpoint

POST https://app.sawt.sa/api/v1/calls/queue/cancel/{phoneNumber}

Path Parameters

string

required

The phone number of the queued call to cancel (e.g., “966501234567”). Accepts numbers with or without the ”+” or “966”/“0” prefix — they are normalized automatically.

Request Headers

required

Bearer your-api-key

application/json

Request Body

string

Optional agent ID to scope the cancellation to a specific agent’s queue. If provided, must be a valid agent belonging to your company.

Example Request

{
  "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d"
}

The request body is optional — an empty body is valid if you don’t need to scope by agentId.

Response

boolean

required

Whether the request was processed successfully

object

required

Cancellation result object containing:

boolean

required

Whether a pending call was found and cancelled

string

required

The normalized phone number

string

The ID of the cancelled queue item (only present when cancelled is true)

string

The queue item’s status before cancellation (only present when cancelled is true)

string

The queue item’s new status, always "CANCELLED" (only present when cancelled is true)

string

The batch ID the call belonged to, if it was part of a batch (only present when cancelled is true)

Example Response (call cancelled)

{
  "success": true,
  "data": {
    "callQueueId": "cq_abc123",
    "phoneNumber": "966501234567",
    "previousStatus": "PENDING",
    "status": "CANCELLED",
    "batchId": "batch_xyz789",
    "cancelled": true
  }
}

Example Response (no pending call found)

{
  "success": true,
  "message": "No pending call found for this phone number",
  "data": {
    "phoneNumber": "966501234567",
    "cancelled": false
  }
}

Error Handling

string

Error message if the request fails

Only calls with status PENDING in a batch with status PENDING, SCHEDULED, QUEUED, ONGOING, or PAUSED are cancellable. Calls that have already started, completed, or failed cannot be cancelled.

Example Error Responses

{
  "error": "Invalid phone number format"
}

{
  "error": "Agent not found or does not belong to your company"
}

{
  "error": "API key missing company information"
}

curl -X POST "https://app.sawt.sa/api/v1/calls/queue/cancel/966501234567" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d"
  }'

const axios = require("axios");

const cancelQueuedCall = async (phoneNumber) => {
  try {
    const response = await axios.post(
      `https://app.sawt.sa/api/v1/calls/queue/cancel/${phoneNumber}`,
      {
        agentId: "e63355c6-cf51-40f3-b006-b615d9ab762d",
      },
      {
        headers: {
          Authorization: "Bearer your-api-key",
          "Content-Type": "application/json",
        },
      }
    );

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

cancelQueuedCall("966501234567");

import requests

def cancel_queued_call(phone_number):
    url = f"https://app.sawt.sa/api/v1/calls/queue/cancel/{phone_number}"

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

    data = {
        "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d"
    }

    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 = cancel_queued_call("966501234567")
print(result)

Sawt API Introduction

Voice Call Endpoints

Speech Services

API Endpoint

Path Parameters

Request Headers

Request Body

Response

Error Handling