Outbound Notifications API (SMS Channel)

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.

Outbound Notifications API Details

The Outbound Notifications API lets clients send outbound notification messages in bulk through Talkdesk's outbound messaging service. 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 linked to active Talkdesk conversations.

Channel support

The API supports the following channels:

• WhatsApp — two message types: direct content messages and template-based messages. For contacts without reply in the last 24 hours, only WhatsApp template messages are permitted.
• 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
• Operation ID: SendOutboundNotificationMessage
• Authentication Scope: outbound-notifications:write

Request body

Content type: application/json

Top-level request schema:

messages[].destinations[] (common)

WhatsApp message format

When channel is WHATSAPP, each item in messages[] must provide exactly one of content or template.

Text message body example:

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

Supported direct body variants:

Template messages

The template must be approved by Meta. Provide the WhatsApp template metadata:

WhatsApp example request:

{
  "channel": "WHATSAPP",
  "sender": "+123456789",
  "messages": [
    {
      "destinations": [
        { "to": "+987654321", "message_id": "client-msg-1" }
      ],
      "template": {
        "name": "welcome_message",
        "language": "en",
        "variables": { "1": "Talkdesk", "2": "Support Team" }
      }
    }
  ],
  "options": {
    "bulk_id": "bulk-123",
    "bind_conversation": { "enabled": true, "ttl_in_minutes": 1440 }
  }
}

SMS message format

When channel is SMS, each item in messages[] must include a body field.

📘

Note: SMS does not support content or template fields.

SMS example request:

{
  "channel": "SMS",
  "sender": "+123456789",
  "messages": [
    {
      "destinations": [ { "to": "+987654321", "message_id": "sms-msg-1" } ],
      "body": "Your order #12345 has been shipped."
    }
  ],
  "options": {
    "bulk_id": "sms-bulk-456",
    "group_id": "shipping-notifications"
  }
}

Request options

options.bind_conversation

Success response

Status code: 202 Accepted

messages[] (Response)

Example Response:

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

Error responses

Notes

• The request is batch-oriented: up to 500 messages per call.
• The response confirms acceptance, not final delivery.
• WhatsApp messages are delivered via Infobip; SMS messages via Twilio.
• bind_conversation only applies to WhatsApp.