Whatsapp messaging

Send a Whatsapp message

Changed on

Sends a WhatsApp message using a Telnyx WhatsApp-enabled number. The message body, interactive elements, media, location, and reaction content are specified in the whatsapp_message field. Delivery progress and final disposition are reported asynchronously through messaging webhooks.

post/messages/whatsapp

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/messages/whatsapp
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional opaque, unquoted key for safely retrying the same logical request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores. Generate a unique UUID v4 for each operation and reuse it only when retrying that operation with the same request. Invalid headers—including duplicate, empty, malformed, or overlong values—return 400 with error code 10015. A request already in progress with the same key returns 409; reusing the key with a different request returns 422. Only successful responses are replayed, for up to 24 hours. Do not include sensitive data in the key.

Request body

fromstring required

Phone number in +E.164 format associated with Whatsapp account

tostring required

Recipient phone number in +E.164 format, or the business-scoped user ID (BSUID) of a WhatsApp user who hides their phone number, for example US.13491208655302741918. Authentication templates cannot be sent to a BSUID.

type'WHATSAPP'

Message type - must be set to "WHATSAPP"

webhook_urlstring url

The URL where webhooks related to this message will be sent.

messaging_profile_idstring uuid

Messaging profile ID - required if the 'from' number is not SMS-enabled

Example request

{
  "from": "+13125551234",
  "to": "+13125551234",
  "whatsapp_message": {
    "audio": {
      "link": "http://example.com/media.jpg"
    },
    "document": {
      "link": "http://example.com/media.jpg"
    },
    "image": {
      "link": "http://example.com/media.jpg"
    },
    "sticker": {
      "link": "http://example.com/media.jpg"
    },
    "video": {
      "link": "http://example.com/media.jpg"
    },
    "interactive": {
      "action": {
        "cards": [
          {
            "header": {
              "image": {
                "link": "http://example.com/media.jpg"
              },
              "video": {
                "link": "http://example.com/media.jpg"
              }
            }
          }
        ]
      },
      "header": {
        "document": {
          "link": "http://example.com/media.jpg"
        },
        "image": {
          "link": "http://example.com/media.jpg"
        },
        "video": {
          "link": "http://example.com/media.jpg"
        }
      }
    },
    "text": {
      "body": "Hello from Telnyx!"
    },
    "template": {
      "template_id": "019cd44b-3a1c-781b-956e-bd33e9fd2ac6",
      "name": "order_confirmation",
      "language": {
        "policy": "deterministic",
        "code": "en_US"
      }
    }
  },
  "type": "WHATSAPP"
}

Response

Successful operation

Example response

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "4031938e-60e4-4235-a8dd-0b1c55a23e7a",
    "type": "WHATSAPP",
    "organization_id": "9f61d8e1-7687-4d6d-9cae-9ff682985983",
    "messaging_profile_id": "4001781e-626f-4a41-a914-b1b682150f94",
    "to": [
      {
        "phone_number": "+13125551234",
        "status": "queued",
        "carrier": "Verizon Wireless",
        "line_type": "Wireless"
      }
    ],
    "body": {
      "audio": {
        "link": "http://example.com/media.jpg"
      },
      "document": {
        "link": "http://example.com/media.jpg"
      },
      "image": {
        "link": "http://example.com/media.jpg"
      },
      "sticker": {
        "link": "http://example.com/media.jpg"
      },
      "video": {
        "link": "http://example.com/media.jpg"
      },
      "interactive": {
        "action": {
          "cards": [
            {
              "header": {
                "image": {
                  "link": "http://example.com/media.jpg"
                },
                "video": {
                  "link": "http://example.com/media.jpg"
                }
              }
            }
          ]
        },
        "header": {
          "document": {
            "link": "http://example.com/media.jpg"
          },
          "image": {
            "link": "http://example.com/media.jpg"
          },
          "video": {
            "link": "http://example.com/media.jpg"
          }
        }
      },
      "text": {
        "body": "Hello from Telnyx!"
      },
      "template": {
        "template_id": "019cd44b-3a1c-781b-956e-bd33e9fd2ac6",
        "name": "order_confirmation",
        "language": {
          "policy": "deterministic",
          "code": "en_US"
        }
      }
    },
    "encoding": "utf-8",
    "wait_seconds": 0.5
  }
}

Changes

  • 90422ac0fcf5Revision changes
    • info

      added the new optional header request parameter Idempotency-Key

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

  • 9a5085a4f2abRevision changes
    • breaking

      added the new required request property ////

    • breaking

      added the new required request property ///

    • breaking

      the /// request property type changed from string to object

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the new optional request property //////

    • info

      added the new action enum value to the request property //////

    • info

      added the new flow enum value to the request property //

    • info

      added the new flow enum value to the request property ////