openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Whatsapp messaging API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Send Whatsapp messages
  name: Whatsapp messaging
paths:
  /messages/whatsapp:
    post:
      operationId: SendWhatsappMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappMessage'
        description: Whatsapp message body
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsappResponse'
          description: Successful operation
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: Send a Whatsapp message
      tags:
      - Whatsapp messaging
      x-hidden: true
      x-latency-category: responsive
components:
  schemas:
    WhatsappResponse:
      properties:
        data:
          properties:
            body:
              $ref: '#/components/schemas/WhatsappMessageContent'
            direction:
              example: outbound
              type: string
            encoding:
              example: utf-8
              type: string
            from:
              properties:
                carrier:
                  description: The carrier of the sender.
                  type: string
                line_type:
                  description: The line-type of the sender.
                  enum:
                  - Wireline
                  - Wireless
                  - VoWiFi
                  - VoIP
                  - Pre-Paid Wireless
                  - ''
                  type: string
                phone_number:
                  description: Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
                  type: string
                  x-format: address
                status:
                  enum:
                  - received
                  - delivered
                  type: string
              type: object
            id:
              description: message ID
              example: 4031938e-60e4-4235-a8dd-0b1c55a23e7a
              type: string
            messaging_profile_id:
              example: 4001781e-626f-4a41-a914-b1b682150f94
              type: string
            organization_id:
              example: 9f61d8e1-7687-4d6d-9cae-9ff682985983
              type: string
            received_at:
              format: date-time
              type: string
            record_type:
              example: message
              type: string
            to:
              $ref: '#/components/schemas/RCSTo'
            type:
              example: WHATSAPP
              type: string
            wait_seconds:
              description: Seconds the message is queued due to rate limiting before being sent to the carrier. Represents the maximum wait across all applicable rate limits (account, carrier, campaign). 0.0 = no queuing delay.
              example: 0.5
              format: float
              type:
              - number
              - 'null'
          type: object
      type: object
    WhatsappReaction:
      properties:
        emoji:
          type: string
        message_id:
          type: string
      type: object
    WhatsappMedia:
      properties:
        caption:
          description: media caption
          type: string
        filename:
          description: file name with extension
          type: string
        link:
          description: media URL
          example: http://example.com/media.jpg
          format: url
          type: string
        voice:
          description: true if voice message
          type: boolean
      type: object
    RCSToItem:
      properties:
        carrier:
          example: Verizon Wireless
          type: string
        line_type:
          example: Wireless
          type: string
        phone_number:
          example: '+13125551234'
          type: string
        status:
          example: queued
          type: string
      type: object
    messaging_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/messaging_Error'
          type: array
    WhatsappMessage:
      properties:
        from:
          description: Phone number in +E.164 format associated with Whatsapp account
          example: '+13125551234'
          type: string
        messaging_profile_id:
          description: Messaging profile ID - required if the 'from' number is not SMS-enabled
          format: uuid
          type: string
        to:
          description: Phone number in +E.164 format
          example: '+13125551234'
          type: string
        type:
          description: Message type - must be set to "WHATSAPP"
          enum:
          - WHATSAPP
          example: WHATSAPP
          type: string
        webhook_url:
          description: The URL where webhooks related to this message will be sent.
          format: url
          type: string
        whatsapp_message:
          $ref: '#/components/schemas/WhatsappMessageContent'
      required:
      - from
      - to
      - whatsapp_message
      type: object
    WhatsappInteractive:
      properties:
        action:
          properties:
            button:
              type: string
            buttons:
              items:
                properties:
                  reply:
                    properties:
                      id:
                        description: unique identifier for each button, 256 character maximum
                        type: string
                      title:
                        description: button label, 20 character maximum
                        type: string
                    type: object
                  type:
                    enum:
                    - reply
                    type: string
                type: object
              type: array
            cards:
              items:
                properties:
                  action:
                    properties:
                      catalog_id:
                        description: the unique ID of the catalog
                        type: string
                      product_retailer_id:
                        description: the unique retailer ID of the product
                        type: string
                    type: object
                  body:
                    properties:
                      text:
                        description: 160 character maximum, up to 2 line breaks
                        type: string
                    type: object
                  card_index:
                    description: unique index for each card (0-9)
                    type: integer
                  header:
                    properties:
                      image:
                        $ref: '#/components/schemas/WhatsappMedia'
                      type:
                        enum:
                        - image
                        - video
                        type: string
                      video:
                        $ref: '#/components/schemas/WhatsappMedia'
                    type: object
                  type:
                    enum:
                    - cta_url
                    type: string
                type: object
              type: array
            catalog_id:
              type: string
            mode:
              type: string
            name:
              type: string
            parameters:
              properties:
                display_text:
                  description: button label text, 20 character maximum
                  type: string
                url:
                  description: button URL to load when tapped by the user
                  format: url
                  type: string
              type: object
            product_retailer_id:
              type: string
            sections:
              items:
                properties:
                  product_items:
                    items:
                      properties:
                        product_retailer_id:
                          type: string
                      type: object
                    type: array
                  rows:
                    items:
                      properties:
                        description:
                          description: row description, 72 character maximum
                          type: string
                        id:
                          description: arbitrary string identifying the row, 200 character maximum
                          type: string
                        title:
                          description: row title, 24 character maximum
                          type: string
                      type: object
                    type: array
                  title:
                    description: section title, 24 character maximum
                    type: string
                type: object
              type: array
          type: object
        body:
          properties:
            text:
              description: body text, 1024 character maximum
              type: string
          type: object
        footer:
          properties:
            text:
              description: footer text, 60 character maximum
              type: string
          type: object
        header:
          properties:
            document:
              $ref: '#/components/schemas/WhatsappMedia'
            image:
              $ref: '#/components/schemas/WhatsappMedia'
            sub_text:
              type: string
            text:
              description: header text, 60 character maximum
              type: string
            video:
              $ref: '#/components/schemas/WhatsappMedia'
          type: object
        type:
          enum:
          - cta_url
          - list
          - carousel
          - button
          - location_request_message
          type: string
      type: object
    WhatsappMessageContent:
      properties:
        audio:
          $ref: '#/components/schemas/WhatsappMedia'
        biz_opaque_callback_data:
          description: custom data to return with status update
          type: string
        contacts:
          items:
            $ref: '#/components/schemas/WhatsappContact'
          type: array
        document:
          $ref: '#/components/schemas/WhatsappMedia'
        image:
          $ref: '#/components/schemas/WhatsappMedia'
        interactive:
          $ref: '#/components/schemas/WhatsappInteractive'
        location:
          $ref: '#/components/schemas/WhatsappLocation'
        reaction:
          $ref: '#/components/schemas/WhatsappReaction'
        sticker:
          $ref: '#/components/schemas/WhatsappMedia'
        template:
          description: Template message object. Provide either template_id or name + language to identify the template.
          properties:
            components:
              description: Template parameter values for header, body, and button components.
              items:
                properties:
                  index:
                    description: Button index (required for button components)
                    type: integer
                  parameters:
                    items:
                      properties:
                        text:
                          type: string
                        type:
                          enum:
                          - text
                          - image
                          - video
                          - document
                          - currency
                          - date_time
                          type: string
                      type: object
                    type: array
                  sub_type:
                    enum:
                    - quick_reply
                    - url
                    type: string
                  type:
                    enum:
                    - header
                    - body
                    - button
                    type: string
                type: object
              type: array
            language:
              description: Template language. Required unless template_id is provided.
              properties:
                code:
                  description: Language code (e.g. en_US)
                  example: en_US
                  type: string
                policy:
                  example: deterministic
                  type: string
              required:
              - code
              type: object
            name:
              description: Template name as registered with Meta. Required unless template_id is provided.
              example: order_confirmation
              type: string
            template_id:
              description: Telnyx template ID (the id field from template list/get responses). When provided, name and language are resolved automatically.
              example: 019cd44b-3a1c-781b-956e-bd33e9fd2ac6
              type: string
          type: object
        text:
          description: Text message content. Can only be sent within a 24-hour customer service window.
          properties:
            body:
              description: The text message body.
              example: Hello from Telnyx!
              type: string
            preview_url:
              default: false
              description: Whether to show a URL preview in the message.
              type: boolean
          required:
          - body
          type: object
        type:
          enum:
          - audio
          - document
          - image
          - sticker
          - video
          - interactive
          - location
          - template
          - reaction
          - contacts
          - text
          type: string
        video:
          $ref: '#/components/schemas/WhatsappMedia'
      type: object
    messaging_Error:
      properties:
        code:
          type: string
          x-format: integer
        detail:
          type: string
        meta:
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              format: json-pointer
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
    WhatsappContact:
      properties:
        addresses:
          items:
            properties:
              city:
                type: string
              country:
                type: string
              country_code:
                type: string
              state:
                type: string
              street:
                type: string
              type:
                type: string
              zip:
                type: string
            type: object
          type: array
        birthday:
          type: string
        emails:
          items:
            properties:
              email:
                type: string
              type:
                type: string
            type: object
          type: array
        name:
          type: string
        org:
          properties:
            company:
              type: string
            department:
              type: string
            title:
              type: string
          type: object
        phones:
          items:
            properties:
              phone:
                type: string
                x-format: E+164
              type:
                type: string
              wa_id:
                type: string
            type: object
          type: array
        urls:
          items:
            properties:
              type:
                type: string
              url:
                format: url
                type: string
            type: object
          type: array
      type: object
    WhatsappLocation:
      properties:
        address:
          type: string
        latitude:
          type: string
        longitude:
          type: string
        name:
          type: string
      type: object
    RCSTo:
      items:
        $ref: '#/components/schemas/RCSToItem'
      type: array
  responses:
    messaging_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
      description: Unexpected error
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http