Skip to navigation

Inbound SMS

To receive inbound SMS, create a webhook endpoint and configure your account to use it in the API settings tab of the Vonage Developer Dashboard.

Any messages sent to one of your Vonage virtual numbers are sent to your webhook using a GET or POST request. When you receive a message on your webhook, you must send a 200 OK or 204 No Content response. If you don't, then Vonage will assume that you have not received the message and will keep resending it for the next 24 hours.

Concatenated messages need special attention. See concatenated inbound messages.

Anatomy of an Inbound Message

Messages are sent to your webhook endpoint as a JSON object with the following properties:

Key Value Required
type Possible values are:
  • text - standard text
  • unicode - a text message that contains Unicode characters
  • binary - a binary message
 Yes
to The phone number that the message was sent to. This is your virtual number. Yes
msisdn The phone number that this inbound message was sent from. Yes
messageId Vonage's unique identifier for this message. Yes
message-timestamp The UTC±00:00 time when Vonage started to push this inbound message to your webhook endpoint, in the following format: YYYY-MM-DD HH:MM:SS. Yes
timestamp The unix timestamp representation of message-timestamp. No
nonce A random string that adds an extra element of unpredictability into the signature for the request. You use the nonce and timestamp parameters with your shared secret to calculate and validate the signature for inbound messages. If your messages are signed

For messages of type text or unicode

If the type is text or unicode, the following properties appear in the request to your webhook endpoint.

Key Value
text The message body for this inbound message.
keyword The first word in the message body. This is typically used with short codes.

For messages of type binary

If the type is binary, the following properties appear in the request to your webhook endpoint.

Key Value
data The content of this message
udh The hex encoded user data header

For concatenated inbound messages

If a message sent to your virtual number fits within the maximum-permitted length of a single message, the following properties do not appear in the request to your webhook endpoint.

If the message is longer than the maximum number of characters allowed in a single message, you will receive the message in parts and the following properties appear in the request.

Use the concat-ref, concat-total and concat-part properties to construct the message from the individual parts.

Not all carriers support concatenated messages. If the carrier does not support concatenation, the concat field will not be present in the payload.

Key Value
concat true
concat-ref The transaction reference. All parts of this message share this concat-ref.
concat-total The number of parts in this concatenated message.
concat-part The number of this part in the message. The first part of the message is 1.
Improve this page