Overview

The Outbound Notifications API, a Talkdesk Digital Engagement™ solution, allows you to send notification messages at scale through multiple channels, utilizing various message types. You can proactively reach your customers by sending messages via WhatsApp or SMS to multiple recipients in a single batch request.

📘

Use Case

Consider the case where you need to send bulk notifications to your customers — such as order confirmations, appointment reminders, or promotional messages. You can use the Outbound Notifications API to send messages from a WhatsApp or SMS sender you control. For WhatsApp, each message can be sent as free-form content or using pre-approved templates. For SMS, messages are sent as plain text. Each message can target multiple destinations in a single request.

📘

Supported Regions and Base URLs

👍

Access and Registration Authentication

Outbound Notifications API

The Outbound Notifications API lets clients send outbound notification messages in bulk through Talkdesk's outbound messaging service. To send messages, provide the channel, a sender identifier, and an array of messages, each with at least one destination. Content can be sent as plain text or via a pre-approved WhatsApp template, specified by name, language, and optional variables for personalization. Messages are trackable using a unique bulk request identifier and can be grouped with an optional identifier, name, and metadata. Outbound messages can also be linked to active Talkdesk conversations.

Channel support

The API supports the following channels:

WhatsApp — two message types:

• direct content messages
• template-based messages
  • For contacts without reply in the last 24 hours, only WhatsApp template messages are permitted. See this process to register templates.

SMS — one message type:

• plain text messages via the body field

Sender configuration

This operation is asynchronous. A successful call returns 202 Accepted with provider message identifiers and an initial delivery status.

Endpoint

POST https://api.talkdeskapp.com/outbound/notifications

• Method: POST
• Path: /outbound/notifications
• Operation ID: SendOutboundNotificationMessage
• Tag: Outbound Messaging

Authentication

This endpoint requires the Draft security scheme with the following scope:

• outbound-notifications:write

Request body

Content type: application/json

Top-level request schema:

messages[].destinations[] (common)

Each message must include a destinations array with at least one recipient. This schema is shared across all channels:

WhatsApp message format

When channel is WHATSAPP, each item in messages[] must provide exactly one of:

• content — a direct content message
• template — a template-based message

Direct content messages

Due to Meta restrictions, this only applies to contact numbers that have sent messages to the touchpoint sender within the last 24 hours.

When using content, the payload shape follows the WhatsApp content model.

Text message body

{
  "content": {
    "body": {
      "type": "TEXT",
      "text": "Hello, how can I help you?"
    }
  }
}

Supported direct body variants:

Template messages

The template must be approved by Meta. The sending success rate depends on the quality of the sender and the template.

The template's header (text, image, video or document), button types, and carousel card layout are now resolved automatically from the approved WhatsApp template configuration. You only need to send the dynamic values below, and every one of them is optional — a template with no placeholders at all still needs nothing but name and language (see the Example below).

When using a template, provide the WhatsApp template metadata:

template.buttons[]

template.carousel[]

Here's the available language code for the template:

Example:

{
  "template": {
    "name": "welcome_message",
    "language": "en",
    "variables": {
      "1": "Talkdesk",
      "2": "Support Team"
    }
  }
}

Header variables (TEXT header with a placeholder):

{
  "template": {
    "name": "order_notification",
    "language": "en",
    "header_variables": {
      "1": "Wireless Bluetooth Headset"
    },
    "variables": {
      "1": "Jane",
      "2": "ORD20260714"
    }
  }
}

Media header (IMAGE, VIDEO or DOCUMENT — no header_variables needed, the media is resolved from the template configuration):

{
  "template": {
    "name": "video_header_reply",
    "language": "en_US",
    "variables": {
      "1": "Tom",
      "2": "meeting"
    }
  }
}

Buttons (dynamic value for a URL button):

{
  "template": {
    "name": "promotion_offer",
    "language": "en",
    "variables": {
      "1": "Jane"
    },
    "buttons": [
      { "suffix": "579852585149360" }
    ]
  }
}

Carousel template (one entry per card, in card order):

{
  "template": {
    "name": "product_carousel",
    "language": "en",
    "variables": {
      "1": "Jane"
    },
    "carousel": [
      { "variables": { "1": "Giraffe plush", "2": "$29.99" } },
      { "variables": { "1": "Zebra plush", "2": "$19.99" } }
    ]
  }
}

Authentication template (COPY_CODE button, uses buttons[].suffix for the one-time code):

{
  "template": {
    "name": "auth_verification_code",
    "language": "en",
    "variables": {
      "1": "482913"
    },
    "buttons": [
      { "suffix": "482913" }
    ]
  }
}

WhatsApp example request

{
  "channel": "WHATSAPP",
  "sender": "+123456789",
  "messages": [
    {
      "destinations": [
        {
          "to": "+987654321",
          "message_id": "client-msg-1"
        },
        {
          "to": "+5551234567"
        }
      ],
      "template": {
        "name": "welcome_message",
        "language": "en",
        "variables": {
          "1": "Talkdesk",
          "2": "Support Team"
        }
      }
    }
  ],
  "options": {
    "bulk_id": "bulk-123",
    "group_id": "campaign-42",
    "group_name": "Spring promo",
    "group_info": {
      "source": "crm",
      "segment": "vip"
    },
    "bind_conversation": {
      "enabled": true,
      "ttl_in_minutes": 1440
    }
  }
}

SMS message format

When channel is SMS, each item in messages[] must include a body field with the plain text content:

SMS does not support content or template fields. Use body only.

SMS example request

{
  "channel": "SMS",
  "sender": "+123456789",
  "messages": [
    {
      "destinations": [
        {
          "to": "+987654321",
          "message_id": "sms-msg-1"
        }
      ],
      "body": "Your order #12345 has been shipped. Track at: https://example.com/track/12345"
    }
  ],
  "options": {
    "bulk_id": "sms-bulk-456",
    "group_id": "shipping-notifications",
    "group_name": "Order updates"
  }
}

Request options

The optional options object applies settings to the whole request:

options.bind_conversation

Success response

Status code:

• 202 Accepted

Response schema:

messages[] in the response

Example:

{
  "bulk_id": "0f0d3c86-2355-4409-9968-ac871cdf88d0",
  "messages": [
    {
      "message_id": "infobip-msg-id-123",
      "destination": "+987654321",
      "status": "PENDING"
    }
  ]
}

Error responses

Notes

• The request is batch-oriented: one call can submit up to 500 messages.
• The response confirms acceptance, not final delivery.
• A destination can include a client-side message_id for correlation.
• Message grouping and conversation binding are controlled at the request level through options.
• WhatsApp messages are delivered via the Infobip provider. SMS messages are delivered via the Twilio provider.
• SMS does not support template-based messages or direct content messages (content). Use the body field for SMS.
• The bind_conversation option only applies to WhatsApp. It has no effect for SMS.