Outbound messaging

With outbound messaging, you can proactively reach out to your customers without requiring them to message you first. You can use our outbound messaging capabilities for use cases such as:

• Scheduled appointment updates & reminders
• Real-time flight updates & check-in reminders
• Fraud alerts for credit cards & checking accounts
• Product shipment & delivery confirmations
• Account activity alerts
• Ticket purchase confirmation & electronic ticket delivery
• Monthly invoice updates & payment reminders

The simplest way to send an outbound message is with the Notification API. Alternatively, the Create Client API can be used to connect a channel to a specific user and conversation. This guide section describes how all outbound messaging methods work on the platform, and details which one to use for your use case.

Outbound messaging with the notification API

With the notification API, you can send outbound messages directly targeting a user by their phone number. When the notification API is invoked, the messaging platform will automatically match the message to an existing user or conversation if it exists, and create a new one if not. This eliminates the need for you to track whether a user or conversation already exists for the given phone number, as well as the associated IDs.

Note: The notification API is available on the following channels: WhatsApp, Twilio, and MessageBird.

On the other hand, if it's important that your outbound messages be attributed to specific users or conversations, then the notification API might not be appropriate for your use case. The Create Client API gives you more control over where messages will ultimately be stored.

Sending notifications

To send a notification, make a request to the Post Notification API. The destination.integrationId parameter controls which integration the notification will be sent from, in case you have more than one eligible integration. The user's phone number should be included under the destination.destinationId property. Finally, include the contents of the notification using the author and message properties. For example:

curl https://{subdomain}.zendesk.com/sc/v1.1/apps/{app_id}/notifications \
     -X POST \
     --user '{key_id}:{secret}' \
     -H 'content-type: application/json' \
     -d '{
        "destination": {
          "integrationId": "5e1f438bf99fb467810c0ab9",
          "destinationId": "[phone]"
        },
        "author": {
          "role": "appMaker"
        },
        "message": {
          "type": "text",
          "text": "This is an example notification"
        }
      }'

In response, a notification id is generated to track the notification during the delivery process. See the webhook section for how to track the delivery of a notification.

{
  "notification": {
    "_id": "e361392f-7dd3-4bdb-8844-d0d002ac7f72"
  }
}

Note: The notification API and its associated delivery webhooks are only supported in Sunshine Conversations' v1.1 API.

Webhooks

Delivery of a notification follows the same basic delivery flow as regular messages. Notifications can trigger the following notification delivery events:

• notification:delivery:channel
• notification:delivery:user
• notification:delivery:failure

Each step of the delivery is equivalent to the conversation:message:delivery:* events in the v2 API, however the webhook payloads are specific to the notification use case. For more information on what each event means, consult the delivery events documentation.

When reporting a notification's delivery status, each webhook event will include the following information:

• The notification's _id, used to associate delivery events with each other, and with the API call that produced them.
• The destination field, detailing where the notification is attempting to be delivered.
• The matchResult field includes the user, conversation and client that were matched for this notification. The match result could refer to a user that was just created as a result of sending the notification, or it might refer to an existing user and conversation that were already connected to the supplied phone number.

For full payload details and examples, consult the v1.1 API documentation.

Context on replies

When a user replies to a notification, the resulting conversation:message webhook will include information on notifications that have been recently sent in that conversation. The recentNotifications key will include all notifications that have been sent since the last message from the user was received. This can be used as additional context on what the user might be replying to. As usual, the full conversation history can also be retrieved using the List Messages API.

Payload example for conversation:message webhook with notification context:

{
  "app": {
    "id": "5babc57a79ace012bba4781a"
  },
  "webhook": {
    "id": "669ff83802164792425ff896",
    "version": "v2"
  },
  "events": [
    {
      "id": "67e6a2ee9a7d8c90b84a226f",
      "createdAt": "2025-03-28T13:23:58.669Z",
      "type": "conversation:message",
      "payload": {
        "conversation": {
          "id": "0a01d368966f45bb6bd7d41c",
          "type": "personal"
        },
        "message": {
          "id": "67e6a2ee3dadb74ea36d6fc0",
          "received": "2025-03-28T13:23:58.669Z",
          "author": {
            "userId": "4a9006a2b1a17bebf00542ab",
            "type": "user",
            "user": {
              "id": "4a9006a2b1a17bebf00542ab"
            }
          },
          "content": {
            "type": "text",
            "text": "This is a user reply to a notification"
          },
          "source": {
            "type": "whatsapp",
            "integrationId": "5b354bdab42a1d61143ccc26"
          }
        },
        "recentNotifications": [
          {
            "id": "67e6a1843dadb74ea36d6f34",
            "received": "2025-03-28T13:17:56.266Z",
            "author": {
              "avatarUrl": "https://www.gravatar.com/avatar/00000000000000000000000000000000.png?s=200&d=mm",
              "type": "business"
            },
            "content": {
              "type": "text",
              "text": "This is an example notification"
            },
            "source": {
              "type": "api:notifications"
            }
          }
        ]
      }
    }
  ]
}

Using the notification API on WhatsApp

WhatsApp has specific restrictions on the type of messages that can be sent to users in an outbound messaging use case. If the user has never messaged your business before, or if the time elapsed since their most recent message is greater than 24 hours, the user can only be sent a pre-approved WhatsApp message template. For information on how to create your templates and get them approved by WhatsApp, see Message Templates in the WhatsApp documentation.

To send a WhatsApp message template using Zendesk messaging, you can leverage our WhatsApp template reconstruction logic. Template reconstruction allows you to call the notification API using WhatsApp's template message schema, and the payload will be automatically converted into an equivalent Zendesk message for persistence. To leverage template reconstruction, specify the messageSchema parameter when calling the notification API with the value whatsapp. Then, under the message field, supply the payload for a WhatsApp message template. Zendesk will send the template payload as-is to WhatsApp, and store a reconstructed version of it in the conversation history.

Learn more about template reconstruction in the WhatsApp guide page.

Here's an example of how to use the notification API leveraging template reconstruction:

curl https://{subdomain}.zendesk.com/sc/v1.1/apps/{app_id}/notifications \
    -X POST \
    --user '{key_id}:{secret}' \
    -H 'content-type: application/json' \
    -d '{
      "destination": {
        "integrationId": "5e1f438bf99fb467810c0ab9",
        "destinationId": "[phone]"
      },
      "author": {
        "role": "appMaker"
      },
      "messageSchema": "whatsapp",
      "message": {
        "type": "template",
        "template": {
          "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
          "name": "sample_template_name",
          "language": {
            "policy": "deterministic",
            "code": "en"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "Sample Parameter 1"
                },
                {
                  "type": "text",
                  "text": "Sample Parameter 2"
                }
              ]
            }
          ]
        }
      }
    }'

Using correctedDestinationId

When communicating with users in countries whose mobile number format may have changed over time (such as Brazil adding a 9th digit to mobile numbers), businesses might notice that WhatsApp adjusts the phone number format to match their own version of the user's number. For example, if a user signed up to WhatsApp before the format changed, then WhatsApp will still know this user by their old phone number. When invoking the notification API for a user whose phone number does not match what is stored in their WhatsApp profile, you could end up with two distinct users - one with the initial number format used and another with the WhatsApp-corrected format.

To work around this problem, Zendesk will provide a destination.correctedDestinationId field in notification delivery webhooks when it detects that the number supplied does not match WhatsApp's version of the phone number. When you are provided with a correctedDestinationId, it is important to update the phone number format in your notification list accordingly. Zendesk messaging will not automatically update or merge users for you, but will supply the correctedDestinationId for your usage.

To clean up your users and conversations, please implement the following process if you send a notification and the notification:delivery:user or notification:delivery:failure event contains a destination.correctedDestinationId:

1. Unlink the bad client from the user (the one that matches destinationId) using the Remove Client API. The target client for this request will be present in the matchResult of the webhook payload.

2. Link the user to the client that you know is correct with the Create Client API. Calling this API triggers a channel transfer. Depending on whether or not a client already exists with the correctedDestinationId, this API triggers a merge, or a client theft.

Going forward, refrain from using the faulty phone number in future notifications; instead, always use the updated phone number supplied to you in the correctedDestinationId field.

Outbound messaging with the create client API

If you know specifically which user and/or conversation you would like to send an outbound message to, then the create client API can be used to accomplish this. Contrary to the notification API which will automatically find or create a user object, the create client API allows you to provide specific user and conversation ids during the flow. For example, if you use messaging authentication to identify your users with an externalId, you will want to make sure that the client gets linked to the correct authenticated user.

First, you'll want to make sure that a user and conversation exists to hold your outbound message. If no user exists yet, you can use the Create User API to create one:

const apiInstance = new SunshineConversationsClient.UsersApi()
const data = new SunshineConversationsClient.UserCreateBody()

data.externalId = "my-user-to-notify"

await apiInstance.createUser("{appId}", data)

You can then use Create Conversation to create a new conversation for this user, which will be used to attach the new client:

const apiInstance = new SunshineConversationsClient.ConversationsApi()
const data = new SunshineConversationsClient.ConversationCreateBody()

data.type = "personal"
data.participants = [
  {
    userExternalId: "my-user-to-notify"
  }
]

await apiInstance.createConversation("{appId}", data)

Once you know the user and conversation ids that you want to link to, you can use the Create Client API to link the channel of your choice:

const apiInstance = new SunshineConversationsClient.ClientsApi()
const data = new SunshineConversationsClient.ClientCreate()

data.matchCriteria = {
  type: "whatsapp",
  integrationId: "5e1f438bf99fb467810c0ab9",
  phoneNumber: "[phone]"
}
data.confirmation = {
  type: "immediate"
}
data.target = {
  conversationId: "{conversation_id}"
}

await apiInstance.createClient("{appId}", "my-user-to-notify", data)

For more information on how to link a client to an existing user and conversation, see channel transfer via direct API call. After the channel transfer is confirmed, you can send a message in the conversation and it should be delivered to the user. See sending messages for details.

Note: This flow only needs to be done the first time you send an outbound message to the user. If the user, conversation, or client already exists, you should skip the relevant operations above to avoid receiving errors and generating conflicting records.

Once the user is properly linked to the channel, any future messages in the conversation should be automatically delivered.