Alerts - Subscribing API Reference
Action Needed For Vonage Customers Using US Shared Short Codes
Effective immediately, Vonage will no longer accept new programs for Shared Short Codes for A2P messaging. T-Mobile and AT&T's new code of conduct prohibits the use of shared originators for A2P (application to person) traffic. Please migrate any existing Shared Short Code traffic to one of our alternative solutions. To help you with this transition, please use the Vonage guide to alternatives. Please contact us to migrate to a new solution.
This defines the API for Campaign Subscription Management:
- Request - request the list of phone numbers opted out from your campaign, or remove a phone number from the list
- Response - the list of opted out phone numbers or confirmation that the number has been removed.
Request
You use the opt-in API to:
-
Retrieve the list of phone numbers who have opted out from your campaign:
https://rest.nexmo.com/sc/us/alert/opt-in/query/json?api_key=xxxxxxxx&api_secret=xxxxxxxx
-
Remove a phone number from your opt-out list:
https://rest.nexmo.com/sc/us/alert/opt-in/manage/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&msisdn=xxxxxxxxxxxx
This request contains:
Base URL
All requests to the Short Code Event Based Alert API must contain:
-
Either:
https://rest.nexmo.com/sc/us/alert/opt-in/query
https://rest.nexmo.com/sc/us/alert/opt-in/manage
A response object: json or xml
Your base URL becomes either:
https://rest.nexmo.com/sc/us/alert/opt-in/query/json
https://rest.nexmo.com/sc/us/alert/opt-in/manage/json
https://rest.nexmo.com/sc/us/alert/opt-in/query/xml
https://rest.nexmo.com/sc/us/alert/opt-in/manage/xml
Parameters
The following table shows the parameters you use in the request:
Parameter | Description | Required |
---|---|---|
msisdn |
The phone number to resubscribe to your campaign and remove from the opt-out list. | If Your base URL contains https://rest.nexmo.com/sc/us/alert/opt-in/manage . |
page-size |
Return this amount of results in the response. The default value is 100. | No |
page |
Return page-size results from this zero-based index in the response. If your request returns 300 Calls, set page to 2 in order to return Calls 201 to 300. The default value is 0. |
No |
Authentication information
If you are not using applications, you use the following parameters for calls to Vonage API:
Parameter | Description |
---|---|
api_key |
Your Key. For example: api_key=NEXMO_API_KEY |
api_secret |
Your Secret. For example: api_secret=NEXMO_API_SECRET |
Note: You find your Key and Secret in Dashboard.
If you are using signatures to verify your requests use:
Parameter | Description |
---|---|
api_key |
Your Key. For example: api_key=NEXMO_API_KEY |
sig |
The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: sig=SIGNATURE
|
Security
To ensure privacy, you must use HTTPS for all Vonage API requests.
Encoding
Encoding
You submit all requests with a POST or GET call using UTF-8 encoding and URL encoded values. The expected Content-Type
for POST is application/x-www-form-urlencoded
. For calls to a JSON endpoint, we also support:
application/json
application/jsonrequest
application/x-javascript
text/json
text/javascript
text/x-javascript
-
text/x-json
when posting parameters as a JSON object.
Response
Each request you make using this API returns a:
- Response - the status of your request to Vonage in JSON or XML format.
The response is returned either:
- Directly to you. For example, if you are using the command line, you see the response on the command line.
- To a webhook endpoint if you set it in Dashboard.
Each response comes:
- In a specific Format
- With Keys and values
Format
You set the response type using the (link:#request text: Base URL). The following table shows example responses in JSON or XML:
{
"opt-in-count":"3",
"opt-in-list":[
{
"msisdn":"15558937009",
"opt-in":"false",
"opt-out":"true",
"opt-out-date":"2014-06-27 18:31:33"
},
{
"msisdn":"15554908975",
"opt-in":"false",
"opt-out":"true",
"opt-out-date":"2014-07-18 16:20:20"
},
{
"msisdn":"15559912501",
"opt-in":"false",
"opt-in-date": "2014-07-18 15:28:23",
"opt-out":"true",
"opt-out-date":"2014-08-18 23:17:40"
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<opt-in-list opt-in-count="3">
<opt-in
msisdn="121326336101"
opt-in="false"
opt-out="true"
opt-out-date="2014-07-22 12:41:48"
/>
<opt-in
msisdn="121326336102"
opt-in="false"
opt-out="true"
opt-out-date="2014-07-22 13:00:04"
/>
<opt-in
msisdn="12132633680"
opt-in="false"
opt-out="true"
opt-out-date="2014-07-22 11:02:50"
/>
</opt-in-list>
{
"msisdn":"15559301529",
"opt-in":"true",
"opt-in-date":"2014-08-21 17:34:47",
"opt-out":"false"
}
<opt-in
msisdn="13065897298"
opt-in="true"
opt-in-date="2015-09-26 04:46:27"
opt-out="false"
/>
Keys and Values
The response contains the following keys and values:
Key | Value | Response type |
---|---|---|
opt-in-count |
The number of parts the message was split into. | JSON |
opt-in-list |
Contains each opt-in part. For an XML response, the count attribute contains the value of opt-in-count JSON key. | BOTH |
opt-in |
A single opt-in part. | XML |
msisdn |
The phone number that was unsubscribed or resubscribed to your campaign. | BOTH |
opt-in |
true if msisdn is subscribed to your campaign. |
BOTH |
opt-in-date |
The date msisdn was subscribed to your campaign. |
BOTH |
opt-out |
true if msisdn is NOT subscribed to your campaign. |
BOTH |
opt-out-date |
The date msisdn was removed from your campaign. |
BOTH |