Messages API

Beta

The Messaging API is a new API that consolidates all messaging channels. It encapsulates a user (developer) from having to use multiple APIs to interact with our various channels such as SMS, MMS, Viber, Facebook Messenger, etc. The API normalises information across all channels to abstracted to, from and content. This API is currently in Beta.

Download OAS 3 Definition

Improve this specification

Send a Message

POST


        https://api.nexmo.com/v0.1/messages

Host


        https://api.nexmo.com

POST


        /v0.1/messages

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Example	Default
Authorization	Your JSON web token. Read more about JWTs	`Bearer <JWT>`	None
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Request body application/json

Send a Message.

object | Required

string | Required

The type of message that you want to send.

Must be one of: sms, viber_service_msg, messenger, whatsapp or mms

string | Min: 1 | Max: 50

Messenger: The ID of the message recipient. This value should be the from.id value you received in the inbound messenger event.

string | Min: 1 | Max: 50

SMS, Viber, WhatsApp or MMS: The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

from

object | Required

string | Required

The type of message that you want to send.

Must be one of: sms, viber_service_msg, messenger, whatsapp or mms

string | Min: 1 | Max: 50

Your ID for the platform that you are sending from.

Messenger: This value should be the to.id value you received in the inbound messenger event.

Viber: This is your Service Message ID given to you by Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.

string | Min: 1 | Max: 50

SMS: The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

WhatsApp: This is your WhatsApp Business Number given to you by Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.

MMS: US shortcode

message

object | Required

string | Required

The type of message that you are sending.

Messenger: supports text, image, audio, video and file.

Viber Service Messages: supports image, text and custom.

WhatsApp: supports template, text, image, audio, file, video and custom. Maximum outbound media size is 64mb.

SMS: supports text.

MMS: supports image.

Must be one of: text, image, audio, video, file, template or custom

string | Min: 1 | Max: 4096

The text of the message.

Messenger: is limited to 640 characters, including unicode.

SMS: is limited to 1000 characters. The Messages API automatically detects unicode characters when sending SMS and sends the message as a unicode SMS. For more information on how concatenation and encoding please visit: developer.nexmo.com/messaging/sms/guides/concatenation-and-encoding.

Viber: is limited to 1000 characters, including unicode.

WhatsApp: is limited to 4096 characters, including unicode.

object

string | Min: 10 | Max: 2000

The URL of the image attachment. The image file is available for 48 hours after it is created.

messenger and mms supports .jpg, .jpeg, .png and .gif.

whatsapp and viber_service_msg supports .jpg .jpeg, and .png.

string | Min: 1 | Max: 3000

Additional text to accompany the image. Supported by WhatsApp and MMS.

object

string | Min: 10 | Max: 2000

The URL of the audio attachment. The audio file is available for 48 hours after it is created.

messenger supports .mp3.

whatsapp supports .aac, .m4a, .amr, .mp3 and .opus.

object

string | Min: 10 | Max: 2000

The URL of the video attachment.

messenger supports .mp4

whatsapp supports .mp4 and .3gpp. Note, only H.264 video codec and AAC audio codec is supported.

object

string | Min: 10 | Max: 2000

The URL of the file attachment. The file is available for 48 hours after it is created.

messenger supports a wide range of attachments including .zip, .csv and .pdf.

whatsapp supports .pdf, .doc(x), .ppt(x) and .xls(x).'

string | Min: 1 | Max: 3000

Additional text to accompany the image. Only supported by WhatsApp. Optional. Only present if specified.

object

string

The name of the template. For WhatsApp use your Whatsapp namespace (available via Facebook Business Manager), followed by a colon : and the name of the template to use.

array of objects

string

The parameters are an array. The first value being {{1}} in the template.

object

string

The use of different category tags enables the business to send messages for different use cases. For Viber Service Messages the first message sent from a business to a user must be personal, informative & a targeted message - not promotional. By default Nexmo sends the transaction category to Viber Service Messages.

Must be one of: transaction or promotion

integer | Min: 30 | Max: 259200

Set the time-to-live of message to be delivered in seconds. i.e. if the message is not delivered in 600 seconds then delete the message.

string

Viber-specific type definition. To use "template", please contact Nexmo Account Manager to setup your templates. To find out more please visit nexmo.com/products/messages.

object

string

The use of different category tags enables the business to send messages for different use cases. For Facebook Messenger they need to comply with their Messaging Types policy. Nexmo maps our category to their messaging_type. If message_tag is used, then an additional tag for that type is mandatory. By default Nexmo sends the response category to Facebook Messenger.

Must be one of: response, update or message_tag

string

‘A full list of the possible tags is available on developers.facebook.com'

object

string

Please note that WhatsApp deprecated fallback policy in January 2020. Use of the fallback policy will result in a 1020 error in the status callback

Must be one of: deterministic

string

We are using the industry standard, BCP 47, for locales. So in your API call to the /messages API you will need to put “en-GB” and this will refer to the “en_GB” template for WhatsApp. A full list of the possible locales is available on developers.facebook.com.

client_ref

string

Client reference of up to 40 characters. The reference will be present in every message status.

Responses

202 Accepted.

message_uuid

string

The UUID of the message.

Example Responses

202 400

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

{
  "type": "https://www.nexmo.com/messages/Errors#InvalidParams",
  "title": "Invalid Parameters",
  "detail": "Your request parameters did not validate.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}

Message Status Callback

Webhooks to inform about events happening to the message at communication level (has it been delivered, rejected by the provider...).

POST


        https://example.com/webhooks/message-status

Request body application/json

message_uuid

string | Required

The UUID of the message.

object | Required

string | Required

The type of message that you want to send.

One of: sms, viber_service_msg, messenger, whatsapp or mms

string | Min: 1 | Max: 50

Messenger: The ID of the message recipient. This value should be the from.id value you received in the inbound messenger event.

string | Min: 1 | Max: 50

from

object | Required

string | Required

The type of message that you want to send.

One of: sms, viber_service_msg, messenger, whatsapp or mms

string | Min: 1 | Max: 50

Your ID for the platform that you are sending from.

Messenger: This value should be the to.id value you received in the inbound messenger event.

Viber: This is your Service Message ID given to you by Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.

string | Min: 1 | Max: 50

SMS: The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

WhatsApp: This is your WhatsApp Business Number given to you by Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.

MMS: US shortcode

timestamp

string (ISO 8601) | Required

The datetime of when the event occurred.

status

string | Required

The status of the message. The read message status is available for messenger, whatsapp and viber.

One of: submitted, delivered, read, rejected or undeliverable

error

object

integer

The error code. See our errors list for a list of possible errors

string

Text describing the error. See our errors list for a list of possible errors

usage

object

string

The charge currency in ISO 4217 format.

One of: EUR

string

The charge amount as a stringified number.

client_ref

string

The client's reference.

Example Payload

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": {
    "type": "sms"
  },
  "from": {
    "type": "sms"
  },
  "timestamp": "2020-01-01T14:00:00.000Z",
  "status": "delivered"
}

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": {
    "type": "sms",
    "id": "0123456789012345",
    "number": "447700900000"
  },
  "from": {
    "type": "sms",
    "id": "0123456789012345",
    "number": "447700900000"
  },
  "timestamp": "2020-01-01T14:00:00.000Z",
  "status": "delivered",
  "error": {
    "code": 1300,
    "reason": "Not part of the provider network"
  },
  "usage": {
    "currency": "EUR",
    "price": "0.0333"
  },
  "client_ref": "my-personal-reference"
}

Inbound Message Callback

An inbound message from a customer to you.

POST


        https://example.com/webhooks/inbound-message

Request body application/json

message_uuid

string | Required

The UUID of the message.

object | Required

string | Required

The type of message being received.

One of: messenger, mms, whatsapp or viber_service_msg

string

Messenger or Viber: The ID of the recipient.

string | Min: 1 | Max: 50

WhatsApp or MMS: The phone number of the message recipient in the E.164 format.

from

object | Required

string | Required

The type of message being sent.

One of: messenger, mms, whatsapp or viber_service_msg

string

The ID of the sender.

string | Min: 1 | Max: 50

WhatsApp or MMS or Viber: The phone number of the message sender in the E.164 format.

timestamp

string (ISO 8601) | Required

The datetime of when the event occurred.

message

object

string

The type of message being received. whatsapp and messenger supports text, image, audio, video, file and location. WhatsApp maximum inbound size is 64mb. mms supports image. viber supports text.

One of: text, image, audio, video, file or location

string

The body of the message.

object

string | Min: 10 | Max: 2000

The URL of the image attachment. The image file is available for 48 hours after it is created.

messenger and mms supports .jpg, .jpeg, .png and .gif.

whatsapp and viber_service_msg supports .jpg .jpeg, and .png.

string | Min: 1 | Max: 3000

Additional text to accompany the image. Supported by WhatsApp and MMS.

object

string | Min: 10 | Max: 2000

The URL of the audio attachment. The audio file is available for 48 hours after it is created.

messenger supports .mp3.

whatsapp supports .aac, .m4a, .amr, .mp3 and .opus.

object

string | Min: 10 | Max: 2000

The URL of the video attachment. The video file is available for 48 hours after it is created.

messenger and whatsapp supports .mp4.

string | Min: 1 | Max: 3000

Additional text to accompany the image. Only supported by WhatsApp. Only present if specified.

object

string | Min: 10 | Max: 2000

The URL of the file attachment. The file is available for 48 hours after it is created.

messenger supports a wide range of attachments including .zip, .csv and .pdf.

whatsapp supports .pdf, .doc(x), .ppt(x) and .xls(x).'

string | Min: 1 | Max: 3000

Additional text to accompany the image. Only supported by WhatsApp. Optional. Only present if specified.

object

string

The latitude of the location attachment.

string

The longitude of the location attachment.

string

Depending on the provider, this can either be the location on a map or the website of the business at this location.

string

The address of the location attachment.

string

The name of the location attachment.

Example Payload

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": {
    "type": "messenger"
  },
  "from": {
    "type": "messenger"
  },
  "timestamp": "2020-01-01T14:00:00.000Z"
}

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": {
    "type": "messenger",
    "id": "01234567",
    "number": "447700900000"
  },
  "from": {
    "type": "messenger",
    "id": "0123456789012345",
    "number": "447700900000"
  },
  "timestamp": "2020-01-01T14:00:00.000Z",
  "message": {
    "content": {
      "type": "text",
      "text": "Hello World!",
      "image": {
        "url": "https://example.com/image.jpg",
        "caption": "Additional text to accompany the image."
      },
      "audio": {
        "url": "https://example.com/audio.mp3"
      },
      "video": {
        "url": "https://example.com/video.mp4",
        "caption": "Additional text to accompany the image."
      },
      "file": {
        "url": "https://example.com/file.zip",
        "caption": "Additional text to accompany the image."
      },
      "location": {
        "lat": "51.5228349",
        "long": "-0.0854414",
        "address": "15 Bonhill St London EC2A 4DN",
        "name": "Nexmo London"
      }
    }
  }
}