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

# Initiate Outbound Call

> Triggers an outbound voice call from your registered phone number to a destination.

## Prerequisites

Before making outbound calls:

1. **Register a phone number** in Studio → Phone Numbers
2. **Assign an outbound agent** to that phone number
3. **Configure SIP trunk** with your carrier (Twilio, Telnyx, etc.)
4. **Ensure sufficient credits** in your organization account

<Warning>
  The agent assigned to `from_number` must use **Pipeline** or **Realtime** architecture. Text-only agents cannot make voice calls and will return a `400` error.
</Warning>

## How It Works

```
1. Validate phone numbers (E.164 format)
         │
         ▼
2. Look up from_number in database
         ├── Not found → 404 Error
         └── Found → Get assigned outbound agent
                   │
                   ▼
3. Check agent architecture
         ├── Text agent → 400 Error
         └── Voice agent → Continue
                   │
                   ▼
4. Decrypt SIP credentials
         │
         ▼
5. Generate room: outbound_{agentId}_{toNumber}_{timestamp}
         │
         ▼
6. Initiate SIP call via LiveKit
         ├── Success → Return room_name
         └── Timeout (60s) → 408 Error
```

## Phone Number Format

Both numbers must be in **E.164 format**:

| Format           | Valid?                         |
| ---------------- | ------------------------------ |
| `+12025550123`   | ✅                              |
| `+442071838750`  | ✅                              |
| `2025550123`     | ❌ Missing `+` and country code |
| `1-202-555-0123` | ❌ Contains dashes              |

## Related

* [Phone Numbers](/api-reference/phone-numbers) — Register and configure numbers
* [Batch Calling](/platform/batch-calling) — Run large-scale outbound campaigns
* [Telephony Guide](/platform/telephony) — SIP trunk setup


## OpenAPI

````yaml POST /telephony/outbound-call
openapi: 3.1.0
info:
  title: TalkifAI API
  version: 1.0.0
  description: Build and manage AI voice and chat agents programmatically.
servers:
  - url: https://api.talkifai.dev
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Create and manage voice and chat agents
  - name: Voice Calls
    description: Initiate outbound calls and retrieve call data
  - name: Text Chat
    description: Text chat sessions via REST + SSE
  - name: Batch Calling
    description: Run large-scale outbound call campaigns
paths:
  /telephony/outbound-call:
    post:
      tags:
        - Voice Calls
      summary: Initiate Outbound Call
      description: >-
        Triggers an outbound voice call from your registered phone number to a
        destination. The `from_number` must have an outbound agent assigned in
        Studio → Phone Numbers.
      operationId: initiateCall
      parameters:
        - name: to_number
          in: query
          required: true
          schema:
            type: string
          description: Destination phone number in E.164 format
          example: '+12025550123'
        - name: from_number
          in: query
          required: true
          schema:
            type: string
          description: Your registered TalkifAI phone number in E.164 format
          example: '+12025550100'
      responses:
        '200':
          description: Call initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Call initiated successfully
                  room_name:
                    type: string
                    example: outbound_agent_abc123_12025550123_1705320000
                  agent:
                    type: object
                    properties:
                      id:
                        type: string
                        example: agent_abc123
                      name:
                        type: string
                        example: Sales Agent
                  from_number:
                    type: string
                    example: '+12025550100'
                  to_number:
                    type: string
                    example: '+12025550123'
        '400':
          description: Invalid phone number format or text-only agent assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_number:
                  value:
                    detail: Invalid phone number format
                text_agent:
                  value:
                    detail: >-
                      Agent 'Chat Bot' is a text-only agent and cannot make
                      voice calls
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Insufficient balance to make call
        '404':
          description: Phone number not found or no outbound agent assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: >-
                  Phone number +12025550100 not found or has no outbound agent
                  assigned
        '408':
          description: Call timed out — not answered within 60 seconds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Call timed out (no answer)
        '500':
          description: Internal server error or SIP trunk failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          example: ERROR_CODE
  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: Invalid API key
            code: invalid_api_key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: tk_live_...
      description: Your TalkifAI API key. Get it from Studio → Settings → API Keys.

````