SMS API

With the SMS API you can send SMS from your account and lookup messages both messages that you've sent as well as messages sent to your virtual numbers. Numbers are specified in E.164 format. More SMS API documentation is at https://developer.vonage.com/messaging/sms/overview

OpenAPI-Spezifikation herunterladen

Verfügbare Operationen

Send an SMS

Send an SMS

Send an outbound SMS from your Vonage account

posthttps://rest.nexmo.com/sms/:format

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

format

string

Erforderlich

Standardjson

Beispieljson

The format of the response

Muss eines der folgenden sein:jsonxml

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

api_key

string

Min8

Max8

Beispielabcd1234

Your API key. Only required if setting sig.

sig

string

Min16

Max60

Beispiel5d41402abc4b2a76b9719d911017c592

The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See Signing Requests for more details. Note: DO NOT set an Authorization header when using sig.

timestamp

integer

Beispiel1617187200

An integer containing the number of seconds since the epoch (this is sometimes also known as UNIX time). Only required if setting sig. See Signing Requests for more details.

from

string

Erforderlich

BeispielAcmeInc

The name or number the message should be sent from. Alphanumeric senderID's are not supported in all countries, see Global Messaging for more details. If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format.

string

Erforderlich

Min7

Max15

Beispiel447700900000

The number that the message should be sent to. Numbers are specified in E.164 format.

text

string

Erforderlich

BeispielHello World!

The body of the message being sent. If your message contains characters that can be encoded according to the GSM Standard and Extended tables then you can set the type to text. If your message contains characters outside this range, then you will need to set the type to unicode.

ttl

integer

Min20000

Max604800000

Standard259200000

Beispiel900000

Advanced: The duration in milliseconds the delivery of an SMS will be attempted. By default Vonage attempts delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.

status-report-req

boolean

Standardtrue

Advanced: Boolean indicating if you like to receive a Delivery Receipt.

callback

string

Beispielhttps://example.com/sms-dlr

Advanced: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard. Max 100 characters.

message-class

integer

Advanced: The Data Coding Scheme value of the message

Muss eines der folgenden sein:0123

type

string

Standardtext

Beispieltext

Advanced: The format of the message body

Muss eines der folgenden sein:textbinaryunicode

body

string

Beispiel0011223344556677

Advanced: Hex encoded binary data. Depends on type parameter having the value binary.

udh

string

Beispiel06050415811581

Advanced: Your custom Hex encoded User Data Header. Depends on type parameter having the value binary.

protocol-id

integer

Beispiel127

Advanced: The value of the protocol identifier to use. Ensure that the value is aligned with udh.

client-ref

string

Beispielmy-personal-reference

Advanced: You can optionally include your own reference of up to 100 characters.

account-ref

string

Beispielcustomer1234

Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support

entity-id

string

Beispiel1101456324675322134

Advanced: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the Country-Specific Outbound SMS Features

content-id

string

Beispiel1107457532145798767

Advanced: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the Country-Specific Outbound SMS Features

trusted-number

boolean

Beispieltrue

Setting this parameter to true overrides, on a per-message basis, any protections set up via Fraud Defender (Traffic Rules, SMS Burst Protection, AIT Protection).

This parameter only has any effect for accounts subscribed to Fraud Defender Premium.

pool-id

string

Beispielabc123

The ID of the Number Pool to use as the sender of this message. If specified, a number from the pool will be used as the from number. The from parameter is still required even when specifying a pool-id and will be used as a fall-back if the number pool cannot be used. See the Number Pools documentation for more information.

Beispiel Anfrage

POST /sms/:format HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 430

api_key=abcd1234&sig=5d41402abc4b2a76b9719d911017c592&timestamp=1617187200&from=AcmeInc&to=447700900000&text=Hello+World!&ttl=900000&status-report-req=false&callback=https://example.com/sms-dlr&message-class=0&type=text&body=0011223344556677&udh=06050415811581&protocol-id=127&client-ref=my-personal-reference&account-ref=customer1234&entity-id=1101456324675322134&content-id=1107457532145798767&trusted-number=true&pool-id=abc123

POST /sms/:format HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 430

api_key=abcd1234&sig=5d41402abc4b2a76b9719d911017c592&timestamp=1617187200&from=AcmeInc&to=447700900000&text=Hello+World!&ttl=900000&status-report-req=false&callback=https://example.com/sms-dlr&message-class=0&type=text&body=0011223344556677&udh=06050415811581&protocol-id=127&client-ref=my-personal-reference&account-ref=customer1234&entity-id=1101456324675322134&content-id=1107457532145798767&trusted-number=true&pool-id=abc123

Antworten
Inhalt Typ
application/json

Success

Einer der

message-count

string

Beispiel1

The amount of messages in the request

messages

array

string

Beispiel447700900000

The number the message was sent to. Numbers are specified in E.164 format.

message-id

string

Beispielaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID of the message

status

string

Beispiel0

The status of the message. See Troubleshooting Failed SMS.

remaining-balance

string

Beispiel3.14159265

Your estimated remaining balance

message-price

string

Beispiel0.03330000

The estimated cost of the message

network

string

Beispiel12345

The estimated ID of the network of the recipient

client-ref

string

Beispielmy-personal-reference

If a client-ref was included when sending the SMS, this field will be included and hold the value that was sent.

account-ref

string

Beispielcustomer1234

Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support

Beispiel Antwort»Message sent

{
   "message-count": "1",
   "messages": [
      {
         "to": "447700900000",
         "message-id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "status": "0",
         "remaining-balance": "3.14159265",
         "message-price": "0.03330000",
         "network": "12345",
         "client-ref": "my-personal-reference",
         "account-ref": "customer1234"
      }
   ]
}

Delivery Receipt callback

The following are parameters sent in as a delivery receipt callback. You can subscribe to webhooks to receive notification when the delivery status of an SMS that you have sent with Vonage changes.

posthttps://example.com/webhooks/event

Anfrage Körper
Inhalt Typ
application/json

msisdn

string

Beispiel447700900000

The number the message was sent to. Numbers are specified in E.164 format.

string

BeispielAcmeInc

The SenderID you set in from in your request.

network-code

string

Beispiel12345

The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.

messageId

string

Beispiel0A0000001234567B

The Vonage ID for this message.

price

string

Beispiel0.03330000

The cost of the message

status

string

Beispieldelivered

A code that explains where the message is in the delivery process.

scts

string

Beispiel2001011400

When the DLR was received from the carrier in the following format YYMMDDHHMM. For example, 2001011400 is at 2020-01-01 14:00

err-code

string

Beispiel0

The status of the request. Will be a non 0 value if there has been an error, or if the status is unknown. See the Delivery Receipt documentation for more details

api-key

string

Beispielabcd1234

The API key that sent the SMS. This is useful when multiple accounts are sending webhooks to the same endpoint.

message-timestamp

string

Beispiel2020-01-01 12:00:00

The time when Vonage started to push this Delivery Receipt to your webhook endpoint.

Beispiel Nutzlast

{
   "msisdn": "447700900000",
   "to": "AcmeInc",
   "network-code": "12345",
   "messageId": "0A0000001234567B",
   "price": "0.03330000",
   "status": "delivered",
   "scts": "2001011400",
   "err-code": "0",
   "api-key": "abcd1234",
   "message-timestamp": "2020-01-01 12:00:00"
}

Antworten

Your server returns this code if it accepts the callback

Webhaken

Webhooks sind eine Erweiterung einer API, aber anstatt dass Ihr Code Daten anfordert, sendet die API Daten an Sie. Die Daten werden in einer Webanforderung an Ihre Anwendung gesendet.

Um mehr über Webhooks zu erfahren, besuchen Sie unsere Website Webhooks-Dokumentation.

Diese API kann jeden der unten dokumentierten Webhooks an die von Ihnen konfigurierte URL senden. Sie müssen mit einer 200 oder 204 HTTP-Antwort antworten, andernfalls werden die Anfragen erneut versucht.

Verfügbare Operationen

Inbound SMS

Inbound SMS webhook

If you rent one or more virtual numbers from Vonage, inbound messages to that number are sent to your webhook endpoint.

When you receive an inbound message, you must send a 2xx response. If you do not send a 2xx response Vonage will resend the inbound message for the next 24 hours.

posthttps://example.com/webhooks/inbound-sms

Anfrage Körper
Inhalt Typ
application/json

api-key

string

Erforderlich

Beispielabcd1234

The Vonage API Key of the receiving account.

msisdn

string

Erforderlich

Beispiel447700900001

The phone number that this inbound message was sent from. Numbers are specified in E.164 format.

string

Erforderlich

Beispiel447700900000

The phone number the message was sent to. This is your virtual number. Numbers are specified in E.164 format.

messageId

string

Erforderlich

Beispielaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID of the message

text

string

Erforderlich

BeispielHello world

The message body for this inbound message.

type

string

Erforderlich

Beispieltext

Possible values are:

text - standard text.
unicode - URLencoded unicode . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.
binary - a binary message.

keyword

string

Erforderlich

BeispielHELLO

The first word in the message body. Converted to upper case.

message-timestamp

string

Erforderlich

Beispiel{}

The time when Vonage started to push this Delivery Receipt to your webhook endpoint.

timestamp

string

Beispiel1578787200

A unix timestamp representation of message-timestamp.

nonce

string

Beispielaaaaaaaa-bbbb-cccc-dddd-0123456789ab

A random string that forms part of the signed set of parameters, it 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.

concat

string

Beispieltrue

True - if this is a concatenated message. This field does not exist if it is a single message

concat-ref

string

Beispiel1

The transaction reference. All parts of this message share this value.

concat-total

string

Beispiel3

The number of parts in this concatenated message.

concat-part

string

Beispiel2

The number of this part in the message. Counting starts at 1.

data

string(binary)

The content of this message, if type is binary.

udh

string

The hex encoded User Data Header, if type is binary

Beispiel Nutzlast

{
   "api-key": "abcd1234",
   "msisdn": "447700900001",
   "to": "447700900000",
   "messageId": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "text": "Hello world",
   "type": "text",
   "keyword": "HELLO",
   "message-timestamp": {},
   "timestamp": "1578787200",
   "nonce": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "concat": "true",
   "concat-ref": "1",
   "concat-total": "3",
   "concat-part": "2",
   "data": "string",
   "udh": "string"
}

Antworten

Your server returns this code if it accepts the callback

Fehler

Im Folgenden finden Sie eine nicht erschöpfende Liste von Fehlercodes, die bei der Verwendung dieser API auftreten können.

Diese Codes gelten zusätzlich zu unseren generische Fehlercodes.

Code	Informationen
1	Beschreibung Throttled. You are sending SMS faster than the account limit. Auflösung Refer to What is the Throughput Limit for Outbound SMS? for more information.
2	Beschreibung Missing Parameters. Your request is missing one of the required parameters `from`, `to`, `api_key`, `api_secret` or `text`. Auflösung Check your parameters and try again.
3	Beschreibung Invalid Parameters. The value of one or more parameters is invalid. Auflösung Check your parameters and try again.
4	Beschreibung Invalid Credentials. Your API key and/or secret are incorrect, invalid or disabled. Auflösung Visit the Dashboard and check your credentials.
5	Beschreibung Internal Error. An error has occurred in the platform whilst processing this message. Auflösung If the error persists, contact support.
6	Beschreibung Invalid Message. The platform was unable to process this message, for example, an un-recognized number prefix. Auflösung N/A
7	Beschreibung Number Barred. The number you are trying to send messages to is blacklisted and may not receive them. Auflösung N/A
8	Beschreibung Partner Account Barred. Your Vonage account has been suspended. Auflösung Contact support.
9	Beschreibung Partner Quota Violation. You do not have sufficient credit to send the message. Auflösung Top-up and retry.
10	Beschreibung Too Many Existing Binds. The number of simultaneous connections to the platform exceeds your account allocation. Auflösung Back-off and retry.
11	Beschreibung Account Not Enabled For HTTP. This account is not provisioned for the SMS API. Auflösung This error usually indicates that you should use SMPP instead.
12	Beschreibung Message Too Long. The message length exceeds the maximum allowed. Auflösung Send shorter messages.
14	Beschreibung Invalid Signature. The signature supplied could not be verified. Auflösung Check the documentation for signing messages or use one of the SDKs to handle the signing.
15	Beschreibung Invalid Sender Address. You are using a non-authorized sender ID in the `from` field. Auflösung This is most commonly seen in North America, where a Vonage long virtual number or short code is required.
17	Beschreibung Message Blocked by Provider. The messaging provider has chosen to block this message. This may be due to content or restrictions imposed by the provider. Auflösung N/A
22	Beschreibung Invalid Network Code. The network code supplied was either not recognized, or does not match the country of the destination address. Auflösung Check the network code or remove it from your request.
23	Beschreibung Invalid Callback Url. The callback URL supplied was either too long or contained illegal characters. Auflösung Supply a valid URL for the callback.
29	Beschreibung Non-Whitelisted Destination. Your Vonage account is still in demo mode. While in demo mode you must add target numbers to your whitelisted destination list. Auflösung Top-up your account to remove this limitation.
32	Beschreibung Signature And API Secret Disallowed. A signed request may not also present an `api_secret`. Auflösung Remove the API secret from your request, or don't sign the message.
33	Beschreibung Number De-activated. The number you are trying to send messages to is de-activated and may not receive them. Auflösung N/A

SMS API

Verfügbare Operationen

Send an SMS

Authentifizierung

Pfad Parameter

Anfrage Körper Inhalt Typapplication/x-www-form-urlencoded

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort»Message sent

Delivery Receipt callback

Anfrage Körper Inhalt Typapplication/json

Beispiel Nutzlast

Antworten

Webhaken

Verfügbare Operationen

Inbound SMS webhook

Anfrage Körper Inhalt Typapplication/json

Beispiel Nutzlast

Antworten

Fehler

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json