Outbound Notifications API

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

Send bulk notifications such as:

• Order confirmations
• Appointment reminders
• Promotional messages

Messages are sent from a WhatsApp or SMS sender you control and can:

• Target multiple recipients in a single request
• Use free-form content for WhatsApp (within a 24-hour reply window)
• Use pre-approved WhatsApp templates
• Send plain text for SMS

Access and Authentication

• Supported Regions and Base URLs
• Access and Registration
• Authentication

Channel Support

The API supports the following channels:

• WhatsApp: Two message types:

  • Direct content messages
  • Template-based messages

  For contacts without a 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

Request Body

Content-Type: application/json

Top-level 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 include exactly one of:

• content: Direct content message
• template: Template-based message

Direct Content Messages

📘

Due to Meta restrictions, direct content messages only apply 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.

Example:

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

Supported Direct Body Variants

Template Messages

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

When using template, provide the WhatsApp template metadata:

Example:

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

Available Language Codes

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

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 via 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.