Exotel Voice API

openapi: 3.2.0
info:
  title: Exotel Voice API
  description: Exotel is an Indian cloud telephony and customer-engagement (CPaaS) platform.
  version: '1.0'
  contact:
    name: Exotel Developer Support
    url: https://developer.exotel.com
  x-grounding:
    confirmedEndpoints:
    - POST /v1/Accounts/{sid}/Calls/connect
    - GET /v1/Accounts/{sid}/Calls/{CallSid}
    - GET /v1/Accounts/{sid}/Numbers/{Number}
    - POST /v1/Accounts/{sid}/Sms/send
    - POST /v2/accounts/{sid}/campaigns
    - GET /v2/accounts/{sid}/campaigns/{campaign_id}
    - GET /v2/accounts/{sid}/campaigns/{campaign_id}/call-details
    modeledEndpoints:
    - GET /v1/Accounts/{sid}/Calls (bulk list; documented as existing, path follows Exotel convention)
    - GET /v1/Accounts/{sid}/Sms/Messages/{SmsSid} (SMS details; documented as existing, path follows Exotel convention)
    schemaStatus: All request/response body and form-field schemas are modeled from documented parameter lists, not from a vendor-published OpenAPI.
servers:
- url: https://api.exotel.com
  description: Singapore cluster (default)
- url: https://api.in.exotel.com
  description: Mumbai / India cluster
security:
- basicAuth: []
tags:
- name: Voice
  description: Place and control outbound voice calls.
paths:
  /v1/Accounts/{sid}/Calls/connect.json:
    parameters:
    - $ref: '#/components/parameters/AccountSid'
    post:
      operationId: connectCall
      tags:
      - Voice
      summary: Connect two numbers or connect a number to a call flow
      description: Places an outbound call. In the "connect two numbers" mode, Exotel first calls `From`, and when answered connects to `To`. In the "connect to a flow" mode, provide `Url` pointing to an Exotel call flow (App/applet, e.g. `http://my.exotel.com/{sid}/exoml/start_voice/{flow_id}`) instead of `To`. Confirmed endpoint; body schema modeled from documented form parameters.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ConnectCallRequest'
      responses:
        '200':
          description: Call queued/initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API Key/Token.
    TooManyRequests:
      description: Rate limit exceeded (Voice APIs are limited to ~200 calls/minute).
  schemas:
    CallResponse:
      type: object
      properties:
        Sid:
          type: string
        AccountSid:
          type: string
        Status:
          type: string
          enum:
          - queued
          - in-progress
          - completed
          - failed
          - busy
          - no-answer
        From:
          type: string
        To:
          type: string
        PhoneNumberSid:
          type: string
          description: The ExoPhone / virtual number used.
        Direction:
          type: string
        Duration:
          type: integer
        Price:
          type: string
        RecordingUrl:
          type: string
        DateCreated:
          type: string
    ConnectCallRequest:
      type: object
      required:
      - From
      - CallerId
      properties:
        From:
          type: string
          description: The number Exotel calls first (E.164 preferred).
        To:
          type: string
          description: The number to connect to. Use this OR Url.
        Url:
          type: string
          description: An Exotel call-flow URL to connect the call to instead of a second number, e.g. http://my.exotel.com/{sid}/exoml/start_voice/{flow_id}.
        CallerId:
          type: string
          description: Your ExoPhone / virtual number shown as caller ID.
        CallType:
          type: string
          enum:
          - trans
          - promo
          description: Call type classification.
        TimeLimit:
          type: integer
          description: Max call duration in seconds (up to 14400).
        TimeOut:
          type: integer
          description: Ring timeout in seconds.
        WaitUrl:
          type: string
          description: Audio URL to play while the callee is being connected.
        Record:
          type: boolean
          description: Whether to record the call.
        StatusCallback:
          type: string
          description: Webhook URL called on call state changes.
        StatusCallbackEvents:
          type: array
          items:
            type: string
            enum:
            - terminal
            - answered
        CustomField:
          type: string
  parameters:
    AccountSid:
      name: sid
      in: path
      required: true
      description: Your Exotel account Sid (Account SID).
      schema:
        type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication. Username = API Key, Password = API Token (both from Exotel Dashboard -> Settings -> API Settings). May also be embedded in the URL as https://<key>:<token>@<subdomain>/...