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 path | Use instead |
|---|---|
POST /messaging/v1/messages with channel set to SMS | POST /messaging/v1/sms |
POST /messaging/v1/messages with channel set to WHATSAPP | POST /messaging/v1/whatsapp |
GET /messaging/v1/messages/{id} | GET /messaging/v1/sms/{id} or GET /messaging/v1/whatsapp/{id} |
POST /messaging/v1/messages/{id}/read | POST /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
- Change the URL to the channel's path.
- Remove
channel. The path says it now, and the new paths refuse it. - Replace the older fields below. The new paths refuse them too.
- Read
textandfailureReasonin the response, where you readcontentandfailedReason.
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
- SMS or WHATSAPP. Use the path for the channel.Example:
SMS - 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. - 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 path | New paths | |
|---|---|---|
| Reading a message | GET /messages/{id} reads an SMS or a WhatsApp message | Each path reads its own channel. The other channel's id answers 404. |
| The message in the response | content, with text beside it | text, or the field named after the message's type. No content. |
| Why a message wasn't delivered | failedReason | failureReason, as on an email |
| WhatsApp's fields on an SMS | messageType and inServiceWindow, both null | Left out |
| Marking an SMS read | 400 | 404 |
An externalId already on the other channel | You get that message back with 200 | 409, with the code E01007. Nothing is sent. Use a new one. |
Emails were never on these paths. See Send an email.