Skip to main content

The old /messages paths

/messaging/v1/messages keeps working for integrations that already use it, exactly as it did, so nothing you've built needs to change. It's deprecated: new work should use the path for its channel, and you can move a call over whenever you're ready.

Old and new paths​

Old pathUse instead
POST /messaging/v1/messages with channel set to SMSPOST /messaging/v1/sms
POST /messaging/v1/messages with channel set to WHATSAPPPOST /messaging/v1/whatsapp
GET /messaging/v1/messages/{id}GET /messaging/v1/sms/{id} or GET /messaging/v1/whatsapp/{id}
POST /messaging/v1/messages/{id}/readPOST /messaging/v1/whatsapp/{id}/read

Your API key, your base URLs and your webhooks stay the same. A message sent on the old path can be read on the new one. The responses are in the same { "message": … }, with only the fields of the path's channel. See What's different on the new paths.

Move a call over​

  1. Change the URL to the channel's path.
  2. Remove channel. The path says it now, and the new paths refuse it.
  3. Replace the older fields below. The new paths refuse them too.
  4. Read text and failureReason in the response, where you read content and failedReason.
An SMS
- POST /messaging/v1/messages
+ POST /messaging/v1/sms

{
- "channel": "SMS",
"sender": "PonitorMFI",
"recipient": "+231770000000",
"externalId": "order-42",
- "content": "Your order 42 is on its way."
+ "text": "Your order 42 is on its way."
}

What only the old paths take​

  • #channelstringRequiredDeprecated
    SMS or WHATSAPP. Use the path for the channel.
    Example: SMS
  • #contentstring or objectOptionalDeprecated
    Text for SMS, or for WhatsApp an object such as { "type": "text", "text": { "body": "…" } }. Use text, or the field named after the message's type.
    Example: Your Acme order 42 is on its way.
  • #templateId, templateParametersstring, string[]OptionalDeprecated
    A WhatsApp template: the Template ID from WhatsApp › Templates, and all its values in one list. See Send a template. Use template.
    Example: "6f1c2a3e-8b4d-4e5f-9a1b-2c3d4e5f6a7b", ["Blama", "LRD 4,500"]

Every other field works as it does on Send an SMS and Send a WhatsApp message.

What's different on the new paths​

Old pathNew paths
Reading a messageGET /messages/{id} reads an SMS or a WhatsApp messageEach path reads its own channel. The other channel's id answers 404.
The message in the responsecontent, with text beside ittext, or the field named after the message's type. No content.
Why a message wasn't deliveredfailedReasonfailureReason, as on an email
WhatsApp's fields on an SMSmessageType and inServiceWindow, both nullLeft out
Marking an SMS read400404
An externalId already on the other channelYou get that message back with 200409, with the code E01007. Nothing is sent. Use a new one.

Emails were never on these paths. See Send an email.