> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sawt.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Outbound Call

> Initiate an outbound call using a Sawt AI agent

<Note>
  You must have a valid API key to use this endpoint. Make sure the agent is properly configured before making calls.
</Note>

## API Endpoint

```bash theme={null}
POST https://app.sawt.sa/api/v1/calls/outbound
```

## Request Headers

<ParamField header="Authorization" required>
  Bearer your-api-key
</ParamField>

<ParamField header="Content-Type" required>
  application/json
</ParamField>

## Request Body

<ParamField body="phoneNumber" type="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.
</ParamField>

<ParamField body="agentId" type="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.
</ParamField>

<ParamField body="promptVariables" type="object">
  Optional dynamic variables in key-value pairs that inject into your agent's prompt
</ParamField>

<Accordion title="Example Request">
  ```json theme={null}
  {
    "phoneNumber": "966501234567",
    "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
    "promptVariables": {
      "doctor_name": "Dr. Ahmed",
      "date": "Wednesday, October 8, 2025",
      "time": "Wednesday, October 8, 2025"
    }
  }
  ```
</Accordion>

## Response

<ResponseField name="success" type="boolean" required>
  Whether the call was successfully initiated
</ResponseField>

<ResponseField name="data" type="object" required>
  Call details object containing:
</ResponseField>

<ResponseField name="data.callTaskId" type="string" required>
  Unique task ID for tracking the call
</ResponseField>

<ResponseField name="data.webhookId" type="string" required>
  Webhook ID for receiving call status updates
</ResponseField>

<ResponseField name="data.phoneNumber" type="string" required>
  The phone number that was called
</ResponseField>

<ResponseField name="data.agentId" type="string" required>
  The agent ID used for the call
</ResponseField>

<ResponseField name="data.companyId" type="string" required>
  Your company identifier
</ResponseField>

<ResponseField name="data.isTest" type="boolean" required>
  Whether this is a test call
</ResponseField>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "data": {
      "callTaskId": "task_abc123",
      "webhookId": "webhook_xyz789",
      "phoneNumber": "966501234567",
      "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
      "companyId": "company_123",
      "isTest": false
    }
  }
  ```
</Accordion>

## Error Handling

<ResponseField name="error" type="string">
  Error message if the request fails
</ResponseField>

### Common Validation Errors

<Warning>
  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)
</Warning>

<Accordion title="Example Error Responses">
  ```json theme={null}
  {
    "error": "Invalid phone number format"
  }
  ```

  ```json theme={null}
  {
    "error": "Agent is not configured for outbound calls"
  }
  ```

  ```json theme={null}
  {
    "error": "No SIP trunk configured for this agent"
  }
  ```

  ```json theme={null}
  {
    "error": "Phone number format does not match SIP trunk configuration"
  }
  ```
</Accordion>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const axios = require("axios");

  const createOutboundCall = async () => {
    try {
      const response = await axios.post(
        "https://app.sawt.sa/api/v1/calls/outbound",
        {
          phoneNumber: "966501234567",
          agentId: "e63355c6-cf51-40f3-b006-b615d9ab762d",
          promptVariables: {
            doctor_name: "Dr. Ahmed",
            date: "Wednesday, October 8, 2025",
            time: "Wednesday, October 8, 2025"
          }
        },
        {
          headers: {
            Authorization: "Bearer your-api-key",
            "Content-Type": "application/json",
          },
        }
      );

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

  createOutboundCall();
  ```

  ```python Python theme={null}
  import requests

  def create_outbound_call():
      url = "https://app.sawt.sa/api/v1/calls/outbound"
      
      headers = {
          "Authorization": "Bearer your-api-key",
          "Content-Type": "application/json"
      }
      
      data = {
          "phoneNumber": "966501234567",
          "agentId": "e63355c6-cf51-40f3-b006-b615d9ab762d",
          "promptVariables": {
              "doctor_name": "Dr. Ahmed",
              "date": "Wednesday, October 8, 2025",
              "time": "Wednesday, October 8, 2025"
          }
      }
      
      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_outbound_call()
  print(result)
  ```
</RequestExample>

## Webhooks

<Card title="Real-time Call Events" icon="webhook" href="/api-reference/endpoint/webhooks">
  Subscribe to webhooks to receive real-time notifications about call events, analysis results, and more. Configure your webhooks at app.sawt.sa/webhooks/subscriptions.
</Card>