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

# Handle Inbound Call

> Process an incoming call from Twilio. This endpoint is typically called by Twilio webhooks when a call is received.

## Overview

Process an incoming call from Twilio. This endpoint is typically called by Twilio webhooks when a call is received on a configured phone number. The endpoint returns TwiML XML to instruct Twilio how to handle the call.

## Query Parameters

<ParamField body="query" name="agent_id" type="string">
  ID of the AI agent to handle the inbound call. Can also be provided in the request body or determined from the ForwardedFrom phone number.
</ParamField>

## Request Body

This endpoint accepts `application/x-www-form-urlencoded` data from Twilio webhooks.

<ParamField body="body" name="CallSid" type="string" required>
  Twilio call SID (automatically provided by Twilio)
</ParamField>

<ParamField body="body" name="From" type="string" required>
  Caller's phone number (automatically provided by Twilio)
</ParamField>

<ParamField body="body" name="To" type="string" required>
  Called phone number (automatically provided by Twilio)
</ParamField>

<ParamField body="body" name="ForwardedFrom" type="string" optional>
  Forwarded from phone number if the call was forwarded (automatically provided by Twilio)
</ParamField>

<ParamField body="body" name="agent_id" type="string">
  ID of the AI agent to handle the call. Can be provided in query string, request body, or determined from ForwardedFrom phone number.
</ParamField>

<ParamField body="body" name="external_call_id" type="string" optional>
  Optional external call ID for tracking purposes.
</ParamField>

## Example Request

<CodeGroup>
  ```bash With agent_id in query theme={null}
  curl -X POST "https://api.call24x7.ai/inbound_call?agent_id=agent-123" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "CallSid=CA1234567890abcdef&From=%2B1234567890&To=%2B0987654321"
  ```

  ```bash With agent_id in body theme={null}
  curl -X POST https://api.call24x7.ai/inbound_call \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "CallSid=CA1234567890abcdef&From=%2B1234567890&To=%2B0987654321&agent_id=agent-123"
  ```
</CodeGroup>

## Response

On success, this endpoint returns TwiML XML that instructs Twilio to stream the call audio to the Call24x7.AI WebSocket server.

### Success Response (TwiML XML)

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://ws.call24x7.ai/{call_id}" />
  </Connect>
</Response>
```

### Error Response (JSON)

<ResponseField name="success" type="boolean">
  Always `false` for errors
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable error message
</ResponseField>

<ResponseField name="error_code" type="string">
  Error code. Possible values: `MISSING_PARAMS`, `AGENT_NOT_FOUND`, `INSUFFICIENT_BALANCE`, `INTERNAL_ERROR`
</ResponseField>

## Example Error Response

```json theme={null}
{
  "success": false,
  "message": "Missing agent_id in query string, request body, or unable to find agent from ForwardedFrom phone number",
  "error_code": "MISSING_PARAMS"
}
```

## Agent ID Resolution

The `agent_id` can be provided in three ways (checked in order):

1. **Query parameter**: `?agent_id=agent-123`
2. **Request body**: `agent_id=agent-123` in the form data
3. **ForwardedFrom lookup**: If `ForwardedFrom` is provided, the system attempts to find the user by phone number and use their active inbound agent

## Twilio Configuration

To use this endpoint, configure your Twilio phone number's webhook URL to point to:

```
https://api.call24x7.ai/inbound_call?agent_id=YOUR_AGENT_ID
```

Or configure it without the agent\_id and provide it in the request body or use the ForwardedFrom lookup feature.

## Notes

* This endpoint is designed to be called by Twilio webhooks, not directly by your application
* The endpoint returns TwiML XML on success, not JSON
* Ensure your account has sufficient balance before receiving calls
* Calls are billed at \$0.15 per minute with precise second-by-second billing


## OpenAPI

````yaml POST /inbound_call
openapi: 3.0.1
info:
  title: Call24x7.AI API
  description: >-
    API for making AI-powered phone calls. Initiate outbound calls, handle
    inbound calls, and manage your AI agents programmatically.
  version: 1.0.0
  contact:
    name: Call24x7.AI Support
    email: support@call24x7.ai
    url: https://manage.call24x7.ai
servers:
  - url: https://api.call24x7.ai
    description: Production server
security:
  - bearerAuth: []
paths:
  /inbound_call:
    post:
      tags:
        - Calls
      summary: Handle inbound call
      description: >-
        Process an incoming call from Twilio. This endpoint is typically called
        by Twilio webhooks when a call is received.
      operationId: handleInboundCall
      parameters:
        - name: agent_id
          in: query
          description: ID of the AI agent to handle the inbound call
          required: false
          schema:
            type: string
      requestBody:
        description: Twilio webhook parameters
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/InboundCallRequest'
      responses:
        '200':
          description: TwiML response for Twilio
          content:
            application/xml:
              schema:
                type: string
                description: TwiML XML response
        '400':
          description: Bad request - missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    InboundCallRequest:
      type: object
      description: Twilio webhook parameters for inbound calls
      properties:
        CallSid:
          type: string
          description: Twilio call SID
        From:
          type: string
          description: Caller's phone number
        To:
          type: string
          description: Called phone number
        ForwardedFrom:
          type: string
          description: Forwarded from phone number (if call was forwarded)
        agent_id:
          type: string
          description: ID of the AI agent to handle the call
        external_call_id:
          type: string
          description: Optional external call ID for tracking
    Error:
      type: object
      required:
        - success
        - message
        - error_code
      properties:
        success:
          type: boolean
          description: Always false for errors
          example: false
        message:
          type: string
          description: Human-readable error message
        error_code:
          type: string
          description: Machine-readable error code
          enum:
            - MISSING_PARAMS
            - UNAUTHORIZED
            - INSUFFICIENT_BALANCE
            - AGENT_NOT_FOUND
            - CALL_NOT_FOUND
            - INTERNAL_ERROR
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key authentication. Include your API key in the Authorization header
        as: Bearer YOUR_API_KEY

````