Send Transactional WhatsApp Messages with OAuth 2.0

WhatsApp Transactional API v2 is a REST API that enables partner systems to send transactional messages through the WhatsApp Business Platform.

To send transactional WhatsApp messages using OAuth 2.0, you must first generate an OAuth 2.0 credential. For step-by-step instructions, refer to OAuth 2.0 Credentials.

Before sending Transactional WhatsApp template messages, make sure you create your template in InOne first. Refer to Create a WhatsApp Business Standard Template on InOne for step-by-step guidance.

Refer to the visual below for an example of how a transactional WhatsApp template message is displayed.

Endpoint and Headers

POST https://whatsapp.useinsider.com/v2/transactional/messages/send

Visit our Postman collection to test this request.

Sample Request

{
        "from": "+905551234567",
        "messages": [
        {
        "phone_number": "+905559876543",
        "user_id": "user-uuid-123",
        "message": {
        "type": "template",
        "template": {
        "name": "welcome_message",
        "language": {
        "code": "tr"
        },
        "components": [
        {
        "type": "body",
        "parameters": [
        {
        "type": "text",
        "text": "Ahmet"
        }
        ]
        }
        ]
        }
        }
        }
        ]
        }

Main Body Parameters

Parameter	Type	Required	Description
`from`	string	Yes	Sender’s WhatsApp phone number (in E.164 format)
`messages`	array	Yes	List of messages to be sent (minimum 1 message)
`url_shortener_config`	object	No	URL shortening settings
`url_shortener_config.status`	boolean	No	Enable/disable URL shortening
`url_shortener_config.domain`	string	No	Domain name for shortening
`unique_args`	object	No	Custom parameters (key–value map)
`remove_tracking_params`	boolean	No	Remove tracking parameters

Messages Array Parameters

Each element in the messages array contains:

Parameter	Type	Required	Description
`phone_number`	string	Yes	The recipient's phone number in international `E.164` format (e.g., `+905551234567`).
`user_id`	string	No	A unique identifier for the user within the partner's system, used for cross-platform tracking.
`message`	object	Yes	The core payload containing the message content (see Message Object details below).
`reply_type`	string	No	Defines the automated response category. Values: `first`, `second`, `third`, `other`.
`unique_args`	object	No	A key–value map for passing custom metadata specific to this individual message.

Message Object Structure

Parameter	Type	Required	Description
`type`	string	Yes	Message type: `template`, `text`, `image`, `video`, `document`, `audio`, `location`, `sticker`, `interactive`.
`template`	object	Conditional	Template message (required if `type=template`).
`text`	object	Conditional	Text message (required if `type=text`).
`...`	`...`	`...`	Other media types follow the same logic.
`context`	object	No	Information about the message being replied to (reply-to message).

Template Messages

Used to send template messages. Templates must be pre-created and approved in the Meta Business Manager.

Parameter	Type	Required	Description
`name`	string	Yes	Template name (must be defined in Meta).
`language`	object	Yes	Template language settings.
`language.code`	string	Yes	Language code (ISO 639-1, e.g., `tr`, `en`, `ar`).
`language.policy`	string	No	Language policy: `deterministic` (default) or `fallback`.
`components`	array	No	Template components (for parameters).

Component Types

Templates can include the following component types:

Header Component

The header component corresponds to the template's header section.

{
        "type": "header",
        "parameters": [
        {
        "type": "text",
        "text": "Değişken başlık değeri"
        }
        ]
        }

To use a media header, you can use the request below.

{
        "type": "header",
        "parameters": [
        {
        "type": "image",
        "image": {
        "link": "https://example.com/image.jpg"
        }
        }
        ]
        }

Header parameter types can be text, image, video and document.

Body Component

Body component is the main text section of the template.

{
        "type": "body",
        "parameters": [
        {
        "type": "text",
        "text": "Ahmet Yılmaz"
        },
        {
        "type": "text",
        "text": "12345"
        }
        ]
        }

Button Component

The main text section of the template.

{
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
        {
        "type": "text",
        "text": "PROMO2024"
        }
        ]
        }

To add buttons to the template, use the request below.

{
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
        {
        "type": "text",
        "text": "PROMO2024"
        }
        ]
        }

To add CTA (Call-to-Action) links to your template, use the request below.

{
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
        {
        "type": "text",
        "cta_link": "?code=SUMMER2024"
        }
        ]
        }

Button sub_types are url and quick_reply.

Carousel Component

Carousel template (product catalog cards).

{
        "type": "carousel",
        "cards": [
        {
        "card_index": 0,
        "components": [
        {
        "type": "header",
        "parameters": [
        {
        "type": "image",
        "image": {
        "link": "https://example.com/product1.jpg"
        }
        }
        ]
        },
        {
        "type": "body",
        "parameters": [
        {
        "type": "text",
        "text": "Ürün 1 Adı"
        },
        {
        "type": "text",
        "text": "999.99 TL"
        }
        ]
        },
        {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
        {
        "type": "text",
        "text": "product-1-slug"
        }
        ]
        }
        ]
        },
        {
        "card_index": 1,
        "components": [
        {
        "type": "header",
        "parameters": [
        {
        "type": "image",
        "image": {
        "link": "https://example.com/product2.jpg"
        }
        }
        ]
        },
        {
        "type": "body",
        "parameters": [
        {
        "type": "text",
        "text": "Ürün 2 Adı"
        },
        {
        "type": "text",
        "text": "1299.99 TL"
        }
        ]
        }
        ]
        }
        ]
        }

Carousel template can contain a maximum of 10 cards (card_index: 0-9).

Limited Time Offer (LTO) Component

{
        "type": "limited_time_offer",
        "parameters": [
        {
        "type": "limited_time_offer",
        "limited_time_offer": {
        "expiration_time_ms": 1640000000000
        }
        }
        ]
        }

Coupon Code Component

{
        "type": "button",
        "sub_type": "copy_code",
        "index": "0",
        "parameters": [
        {
        "type": "coupon_code",
        "coupon_code": "SUMMER2024"
        }
        ]
        }

Flow Button Component (For WhatsApp Flows)

{
        "type": "button",
        "sub_type": "flow",
        "index": "0",
        "parameters": [
        {
        "type": "action",
        "action": {
        "flow_token": "unique-flow-token",
        "flow_action_data": {
        "user_id": "12345",
        "product_id": "SKU-123"
        }
        }
        }
        ]
        }

Text Message

Used to send plain text messages (typically for conversational use).

Parameters

Parameter	Type	Required	Description
`body`	string	Yes	Message text (maximum `4096` characters).
`preview_url`	boolean	No	Display URL preview (default: `false`).

{
        "type": "text",
        "text": {
        "body": "Merhaba! Siparişiniz hazırlanıyor.",
        "preview_url": false
        }
        }

Image Message

Used to send images.

Image Object

Parameter	Type	Required	Description
`link`	string	Conditional	Image URL (`HTTP`/`HTTPS`, mandatory if `id` is missing).
`id`	string	Conditional	Uploaded media ID (mandatory if `link` is missing).
`caption`	string	No	Image caption (maximum `1024` characters).

Image Message with Link

{
        "type": "image",
        "image": {
        "link": "https://example.com/image.jpg",
        "caption": "Product Image"
        }
        }

Image Message with Media ID

{
        "type": "image",
        "image": {
        "id": "1234567890",
        "caption": "Uploaded Image"
        }
        }

Supported formats for image messages are JPEG, PNG. The maximum size is 5 MB.

Video Message

Used to send videos.

Parameter	Type	Required	Description
`link`	string	Conditional	Video URL (`HTTP`/`HTTPS`, mandatory if `id` is missing).
`id`	string	Conditional	Uploaded media ID (mandatory if `link` is missing).
`caption`	string	No	Video caption (maximum `1024` characters).

{
        "type": "video",
        "video": {
        "link": "https://example.com/video.mp4",
        "caption": "Product video"
        }
        }

Supported formats for video messages are MP4 and 3GPP. The maximum size is 16 MB.

Document Message

Used to send documents/files.

Parameter	Type	Required	Description
`link`	string	Conditional	Document URL (`HTTP`/`HTTPS`, mandatory if `id` is missing).
`id`	string	Conditional	Uploaded media ID (mandatory if `link` is missing).
`filename`	string	No	Filename (to be displayed).
`caption`	string	No	Document caption (maximum `1024` characters).

{
        "type": "document",
        "document": {
        "link": "https://example.com/invoice.pdf",
        "filename": "Fatura-12345.pdf",
        "caption": "Sipariş faturanız"
        }
        }

Supported formats for document messages are PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT and CSV. The maximum size is 100 MB.

Audio Message

Used to send audio files.

Parameter	Type	Required	Description
`link`	string	Conditional	Audio URL (`HTTP`/`HTTPS`, mandatory if `id` is missing).
`id`	string	Conditional	Uploaded media ID (mandatory if `link` is missing).

{
        "type": "audio",
        "audio": {
        "link": "https://example.com/audio.mp3"
        }
        }

Supported formats for audio messages are AAC, M4A, AMR, MP3 and OGG OPUS. The maximum size is 16 MB.

Location Message

Used to send location/map coordinates.

Location Object

Parameter	Type	Required	Description
`latitude`	string	Yes	Latitude coordinate.
`longitude`	string	Yes	Longitude coordinate.
`name`	string	No	Location name.
`address`	string	No	Location address.

{
        "type": "location",
        "location": {
        "latitude": "41.0082",
        "longitude": "28.9784",
        "name": "İstanbul",
        "address": "İstanbul, Türkiye"
        }
        }

Sticker Message

Used to send stickers.

Parameter	Type	Required	Description
`link`	string	Conditional	Sticker URL (`HTTP`/`HTTPS`, mandatory if `id` is missing).
`id`	string	Conditional	Uploaded media ID (mandatory if `link` is missing).

{
        "type": "sticker",
        "sticker": {
        "link": "https://example.com/sticker.webp"
        }
        }

Supported format for sticker messages is WebP (static or animated) The maximum size is 100 KB (static), 500 KB (animated).

Interactive Message

Used to send interactive messages (buttons, lists, products, flows).

Parameter	Type	Required	Description
`type`	string	Yes	Interactive type: `button`, `list`, `product`, `product_list`, `flow`, `catalog_message`, `cta_url`.
`header`	object	No	Message header.
`body`	object	Yes	Message main body.
`body.text`	string	Yes	Message text (maximum `1024` characters).
`footer`	object	No	Message footer.
`footer.text`	string	Yes	Footer text (maximum `60` characters).
`action`	object	Yes	Interactive action definition.

Interactive Header

"header": {

        "type": "text",

        "text": "Başlık metni"

        }

Media Header

"header": {

        "type": "image",

        "image": {

        "link": "https://example.com/header.jpg"

        }

        }

Header types can be text, image, video, document.

Interactive Action Types

Button Action - Reply buttons (maximum 3 buttons)

"action": {
        "buttons": [
        {
        "type": "reply",
        "reply": {
        "id": "btn_yes",
        "title": "Evet"
        }
        },
        {
        "type": "reply",
        "reply": {
        "id": "btn_no",
        "title": "Hayır"
        }
        }
        ]
        }

Button title can be a maximum 20 characters.

List Action - Selection list (maximum 10 rows)

"action": {
        "button": "Seçenekleri Gör",
        "sections": [
        {
        "title": "Kategori 1",
        "rows": [
        {
        "id": "row_1",
        "title": "Seçenek 1",
        "description": "Seçenek açıklaması"
        },
        {
        "id": "row_2",
        "title": "Seçenek 2",
        "description": "Diğer seçenek"
        }
        ]
        }
        ]
        }

Product Action - Single product display

"action": {
        "catalog_id": "123456789",
        "product_retailer_id": "SKU-12345"
        }

Product List Action - List of products

"action": {

                "catalog_id": "123456789",

                "sections": [

                {

                "title": "Öne Çıkan Ürünler",

                "product_items": [

                {

                "product_retailer_id": "SKU-001"

                },

                {

                "product_retailer_id": "SKU-002"

                }

                ]

                }

                ]

                }

Flow Action - WhatsApp Flows

"action": {

                "name": "flow",

                "parameters": {

                "flow_message_version": "3",

                "flow_token": "unique-token",

                "flow_id": "123456789",

                "flow_cta": "Form Doldur",

                "flow_action": "navigate",

                "flow_action_payload": {

                "screen": "FORM_SCREEN",

                "data": {

                "user_id": "12345"

                }

                }

                }

                }

CTA URL Action - External link button

"action": {

                "name": "cta_url",

                "parameters": {

                "display_text": "Web Siteyi Ziyaret Et",

                "url": "https://example.com"

                }

                }

Catalog Message Action - Full catalog display

"action": {

                "name": "catalog_message",

                "parameters": {

                "thumbnail_product_retailer_id": "SKU-FEATURED"

                }

                }

Interactive Carousel - Product carousel (maximum 10 cards)

"action": {

                "cards": [

                {

                "card_index": 0,

                "type": "carousel",

                "header": {

                "type": "image",

                "image": {

                "link": "https://example.com/product1.jpg"

                }

                },

                "body": {

                "text": "Ürün 1 - 999 TL"

                },

                "action": {

                "name": "cta_url",

                "parameters": {

                "display_text": "Satın Al",

                "url": "https://example.com/product/1"

                }

                }

                }

                ]

                }

Context Object

Used to reply to a specific message.

Parameter	Type	Required	Description
`link`	string	Conditional	Sticker URL (`HTTP`/`HTTPS`, mandatory if `id` is missing).
`id`	string	Conditional	Uploaded media ID (mandatory if `link` is missing).

{
        "type": "text",
        "context": {
        "message_id": "wamid.HBgLOTA5NTU1MTIzNDU2NxUCABIYIDNBMzQwRjg2..."
        },
        "text": {
        "body": "Teşekkür ederiz!"
        }
        }

Sample Responses

Response Parameters

Parameter	Type	Description
`keys`	array	Unique keys generated for each message. Used in webhook callbacks.

200 OK - Success Response

{

        "keys": [

        "whatsapp-550e8400-e29b-41d4-a716-446655440000"

        ]

        }

400 Bad Request

{

        "message": "failed to validate request",

        "error": {

        "message": "failed to validate request",

        "code": "2001"

        }

        }

400 Bad Request - Validation

{
        "message": "failed to validate request",
        "error": {
        "message": "failed to validate request",
        "code": "2002"
        }
        }

400 Bad Request - Send Failed

{
        "message": "Message could not be sent.",
        "detail": "There is no active provider.",
        "error": {
        "message": "Message could not be sent.",
        "code": "2003"
        }
        }

Error Codes

Code	HTTP Status	Description
2001	400	The request body could not be decoded.
2002	400	The request body failed validation.
2003	400	The message could not be sent due to a provider error or an internal system issue.

Media Operation Errors

Code	HTTP Status	Description
2017	400	Provider not found or upload error
2018	400	Error retrieving media information
2019	400	Media download error
INVALID_FILE	400	Invalid file or file could not be read

System Errors

HTTP Status	Description
503 Service Unavailable	The system is currently in maintenance mode