Messages API Developer Preview

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 Developer Preview and you will need to request access  to use it.

Download OpenAPI 3 Definition

Message

The Message object contains information about the request and details of the message object.

  • Key
    Description
  • message_uuid
    Required | string

    The UUID of the message.

Example Model

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

Send a Message

POST https://api.nexmo.com/beta /messages

Authentication

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

Request body application/json

  • Key
    Description
    Example
    Default
  • to
    Required | object
    None
    • Key
      Description
      Example
      Default
    • type
      Required | string

      The type of message that you want to send.


      Must be one of: sms, viber_service_msgormessenger
      sms
      None
    • id
      string

      The ID of the message recipient.

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

      SMS: or Viber: This value is not required.

      0123456789012345
      None
    • number
      string

      SMS: or Viber: The phone number of the message recipient in the E.164  format.

      Messenger: This value is not required.

      447700900000
      None
  • from
    Required | object
    None
    • Key
      Description
      Example
      Default
    • type
      Required | string

      The type of message that you want to send.


      Must be one of: sms, viber_service_msgormessenger
      sms
      None
    • id
      string

      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 nexm.com/products/messages  .

      SMS: This value is not required.

      0123456789012345
      None
    • number
      string

      SMS: The phone number of the message recipient in the E.164  format.

      Messenger: or Viber: This value is not required.

      447700900000
      None
  • message
    Required | object
    None
    • Key
      Description
      Example
      Default
    • content
      Required | object
      None
      • Key
        Description
        Example
        Default
      • type
        string

        The type of message that you are sending.

        Messenger: supports all types.

        SMS or Viber only support text.


        Must be one of: text, image, audio, video, fileorcustom
        text
        None
      • text
        string

        The text of the message.

        Messenger: Is limited to 640 characters

        SMS or Viber: Is 1000 characters

        Hello world!
        None
      • image
        object
        None
        • Key
          Description
          Example
          Default
        • url
          string

          The URL of the image attachment.

          https://example.com/image.jpg
          None
      • audio
        object
        None
        • Key
          Description
          Example
          Default
        • url
          string

          The URL of the audio attachment.

          https://example.com/audio.mp3
          None
      • video
        object
        None
        • Key
          Description
          Example
          Default
        • url
          string

          The URL of the video attachment.

          https://example.com/video.mp4
          None
      • file
        object
        None
        • Key
          Description
          Example
          Default
        • url
          string

          The URL of the file attachment.

          https://example.com/file.zip
          None
    • viber_service_msg
      object
      None
      • Key
        Description
        Example
        Default
      • 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: transactionorpromotion
        transaction
        None
      • ttl
        integer

        Only valid for Viber Service Messages. 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.


        Must be between 30 and 86400
        600
        None
    • messenger
      object
      None
      • Key
        Description
        Example
        Default
      • 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, updateormessage_tag
        message_tag
        None
      • tag
        string

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

        ticket_update
        None

Example request

curl -X POST https://api.nexmo.com/beta/messages \
  -H 'Authorization: Bearer '$JWT\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d $'{
    "from": { "type": "sms", "number": "FROM_NUMBER" },
    "to": { "type": "sms", "number": "TO_NUMBER" },
    "message": {
      "content": {
        "type": "text",
        "text": "This is an SMS sent from the Messages API"
      }
    }
  }'
http POST 'https://api.nexmo.com/beta/messages' \
  'Authorization':'Bearer '$JWT\
  from:='{ "type": "sms", "number": "FROM_NUMBER" }' \
  to:='{ "type": "sms", "number": "TO_NUMBER" }' \
  message:='{
    "content": {
      "type": "text",
      "text": "This is an SMS sent from the Messages API"
    }
  }'
const Nexmo = require('nexmo')

const nexmo = new Nexmo({
  apiKey: NEXMO_API_KEY,
  apiSecret: NEXMO_API_SECRET,
  applicationId: NEXMO_APPLICATION_ID,
  privateKey: NEXMO_APPLICATION_PRIVATE_KEY_PATH
})

nexmo.channel.send(
  { "type": "sms", "number": "TO_NUMBER" },
  { "type": "sms", "number": "FROM_NUMBER" },
  {
    "content": {
      "type": "text",
      "text": "This is an SMS sent from the Messages API"
    }
  },
  (err, data) => { console.log(data.message_uuid); }
);

202 HTTP response

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

400 HTTP response

Callback  Message Status

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

  • Key
    Description
    Example
  • message_uuid
    Required | string

    The UUID of the message.

    aaaaaaaa-bbbb-cccc-dddd-0123456789ab
  • to
    Required | object
    • Key
      Description
      Example
    • type
      Required | string

      The type of message that you want to send.


      One of: sms, viber_service_msgormessenger
      sms
    • id
      string

      The ID of the message recipient.

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

      SMS: or Viber: This value is not required.

      0123456789012345
    • number
      string

      SMS: or Viber: The phone number of the message recipient in the E.164  format.

      Messenger: This value is not required.

      447700900000
  • from
    Required | object
    • Key
      Description
      Example
    • type
      Required | string

      The type of message that you want to send.


      One of: sms, viber_service_msgormessenger
      sms
    • id
      string

      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 nexm.com/products/messages  .

      SMS: This value is not required.

      0123456789012345
    • number
      string

      SMS: The phone number of the message recipient in the E.164  format.

      Messenger: or Viber: This value is not required.

      447700900000
  • timestamp
    Required | string (ISO 8601)

    The datetime of when the event occurred.

    2020-01-01T14:00:00.000Z
  • status
    Required | string

    The status of the message. The read message status is only available for viber_service_msg and messenger.


    One of: submitted, delivered, read, rejectedorundeliverable
    delivered
  • error
    object
    • Key
      Description
      Example
    • code
      integer

      The error code. See Errors for a table of descriptions.

      1300
    • reason
      string

      Text describing the error. See Errors for a more details.

      Not part of the provider network
  • usage
    object
    • Key
      Description
      Example
    • currency
      string

      The charge currency in ISO 4217 format.


      One of: EUR
      EUR
    • price
      string

      The charge amount as a stringified number.

      0.0333

Request model

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

Callback  Inbound Message

An inbound message from a customer to you.

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

Request body application/json

  • Key
    Description
    Example
  • message_uuid
    Required | string

    The UUID of the message.

    aaaaaaaa-bbbb-cccc-dddd-0123456789ab
  • to
    Required | object
    • Key
      Description
      Example
    • type
      Required | string

      The type of message being received.


      One of: messenger
      messenger
    • id
      string

      The ID of the recipient.

      0123456678901234
  • from
    Required | object
    • Key
      Description
      Example
    • type
      Required | string

      The type of message being sent.


      One of: messenger
      messenger
    • id
      string

      The ID of the sender.

      0123456789012345
  • timestamp
    Required | string (ISO 8601)

    The datetime of when the event occurred.

    2020-01-01T14:00:00.000Z
  • message
    object
    • Key
      Description
      Example
    • content
      object
      • Key
        Description
        Example
      • type
        string

        The type of message being received.


        One of: text, image, audio, video, fileorlocation
        text
      • text
        string

        The body of the message.

        Hello World!
      • image
        object
        • Key
          Description
          Example
        • url
          string

          The URL of the image attachment.

          https://example.com/image.jpg
      • audio
        object
        • Key
          Description
          Example
        • url
          string

          The URL of the audio attachment.

          https://example.com/audio.mp3
      • video
        object
        • Key
          Description
          Example
        • url
          string

          The URL of the video attachment.

          https://example.com/video.mp4
      • file
        object
        • Key
          Description
          Example
        • url
          string

          The URL of the file attachment.

          https://example.com/file.zip
      • location
        object
        • Key
          Description
          Example
        • lat
          string

          The latitude of the location attachment.

          51.5228349
        • long
          string

          The longitude of the location attachment.

          -0.0854414
        • url
          string

          The location on a map.

          None

Request model

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": {
    "type": "messenger",
    "id": "0123456678901234"
  },
  "from": {
    "type": "messenger",
    "id": "0123456789012345"
  },
  "timestamp": "2020-01-01T14:00:00.000Z",
  "message": {
    "content": {
      "type": "text",
      "text": "Hello World!",
      "image": {
        "url": "https://example.com/image.jpg"
      },
      "audio": {
        "url": "https://example.com/audio.mp3"
      },
      "video": {
        "url": "https://example.com/video.mp4"
      },
      "file": {
        "url": "https://example.com/file.zip"
      },
      "location": {
        "lat": "51.5228349",
        "long": "-0.0854414",
        "url": "abc123"
      }
    }
  }
}

Errors

Nexmo uses error codes to report back when an issue was encountered. Below you can find a full table to error codes:

Asynchronous Errors

Code Text Meaning
1000 Throttled You have exceeded the submission capacity allowed on this account. Please wait and retry.
1010 Missing params Your request is incomplete and missing some mandatory parameters.
1020 Invalid params The value of one or more parameters is invalid.
1021 Invalid tag The tag value is invalid.
1022 Invalid template parameters Some of the parameters of the template were invalid.
1030 Internal error There was an error processing your request in the Platform.
1040 Invalid message The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.
1050 Number barred The number you are trying to submit to is blacklisted and may not receive messages.
1060 Partner account barred The api_key you supplied is for an account that has been barred from submitting messages.
1070 Partner quota exceeded Your pre-paid account does not have sufficient credit to process this message.
1080 Account not enabled for REST This account is not provisioned for REST submission, you shoud use SMPP on the SMS API.
1090 Message too long The length of udh and body was greater than 140 octets for a binary type SMS request.
1100 Communication Failed Message was not submitted because there was a communication failure.
1110 Invalid Signature Message was not submitted due to a verification failure in the submitted signature.
1120 Illegal Sender Address - rejected Due to local regulations, the SenderID you set in from in the request was not accepted. Please check the Global messaging section.
1130 Invalid TTL The value of ttl in your request was invalid.
1140 Facility not allowed Your request makes use of a facility that is not enabled on your account.
1150 Invalid Message class The value of message-class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.
1160 Non White-listed Destination The phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard.
1170 Invalid or Missing Msisdn Param The phone number you supplied in the to parameter of your request was either missing or invalid.
1180 Absent Subscriber Temporary This message was not delivered because to was temporarily unavailable. For example, the handset used for to was out of coverage or switched off. This is a temporary failure, rety later for a positive result.
1190 Absent Subscriber Permanent to is no longer active, You should remove this phone number from your database.
1200 Portability Error There is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly.
1210 Anti-Spam Rejection Carriers often apply restrictions that block messages following different criteria. For example on SenderID or message content.
1220 Handset Busy The handset associated with to was not available when this message was sent. If status is rejected, this is a temporary failure; retry later for a positive result. If status is submitted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours.
1230 Network Error A network failure while sending your message. This is a temporary failure, retry later for a positive result.
1240 Illegal Number You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you.
1241 Too many send requests Too many send requests to phone numbers.
1250 Unroutable The chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message sent by from. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com.
1260 Destination unreachable The message could not be delivered to the phone number. If using Viber Service Messages your account might not be enabled for this country.
1270 Subscriber Age Restriction The carrier blocked this message because the content is not suitable for to based on age restrictions.
1280 Number Blocked by Carrier The carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended.
1290 Pre-Paid - Insufficent funds to’s pre-paid account does not have enough credit to receive the message.
1300 Not part of the provider network The number or ID is not a user in the provider network.
1310 Not suitable device The user's device can't receive the message.
1320 Message already sent The message was already sent.
1330 Unknown An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid.
1340 Outside of the allowed window This message is sent outside of allowed response window.
1350 Phone matching fee not paid Requires phone matching access fee to be paid by the the Facebook Page.
1360 TTL was activated TTL was activated, no callbacks and no charge will be issued.

Example response

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