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