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