Available Operations
 
 

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.

Available Operations:

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.

to
object | Required
type
string | Required

The type of message that you want to send.

Must be one of: sms, viber_service_msg, messenger, whatsapp or mms
id
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.

number
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
type
string | Required

The type of message that you want to send.

Must be one of: sms, viber_service_msg, messenger, whatsapp or mms
id
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.

number
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
content
object | Required
type
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
text
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.

image
object
url
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.

caption
string | Min: 1 | Max: 3000

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

audio
object
url
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.

video
object
url
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.

file
object
url
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).'

caption
string | Min: 1 | Max: 3000

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

template
object
name
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.

parameters
array of objects
default
string

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

viber_service_msg
object
category
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
ttl
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.

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

messenger
object
category
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
tag
string

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

whatsapp
object
policy
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
locale
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.

to
object | Required
type
string | Required

The type of message that you want to send.

One of: sms, viber_service_msg, messenger, whatsapp or mms
id
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.

number
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
type
string | Required

The type of message that you want to send.

One of: sms, viber_service_msg, messenger, whatsapp or mms
id
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.

number
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
code
integer

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

reason
string

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

usage
object
currency
string

The charge currency in ISO 4217 format.

One of: EUR
price
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.

to
object | Required
type
string | Required

The type of message being received.

One of: messenger, mms, whatsapp or viber_service_msg
id
string

Messenger or Viber: The ID of the recipient.

number
string | Min: 1 | Max: 50

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

from
object | Required
type
string | Required

The type of message being sent.

One of: messenger, mms, whatsapp or viber_service_msg
id
string

The ID of the sender.

number
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
content
object
type
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
text
string

The body of the message.

image
object
url
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.

caption
string | Min: 1 | Max: 3000

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

audio
object
url
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.

video
object
url
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.

caption
string | Min: 1 | Max: 3000

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

file
object
url
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).'

caption
string | Min: 1 | Max: 3000

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

location
object
lat
string

The latitude of the location attachment.

long
string

The longitude of the location attachment.

url
string

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

address
string

The address of the location attachment.

name
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"
      }
    }
  }
}