Syniverse FAQs
Syniverse's Frequently Asked Questions page is a central hub where its customers can always go to with their most common questions. These are the 126 most popular questions Syniverse receives.
Frequently Asked Questions About Syniverse
Group Messaging allows you to send messages from your application to up to 10 Mobile phone recipients as a group that can engage in a 2-way communication at the same time. The group messaging capability is enabled by using the Syniverse MMS service and requires that the application has a valid US TN (Telephone number) with MMS capabilities provisioned.
Prerequisite:
Valid US Telephone Number (Sender ID) with MMS provisioned - For information on how to purchase a US Sender address or migrate your Sender ID, please visit https://developer.syniverse.com
A registered SPID (Service Provider ID)/NNID (Netnumber ID) provisioned on our MMS/SMS-IP platforms
An Opt-in/Opt-out process must be in place for group messaging. Group messaging traffic must be opted in by the recipient and an opt out language must be available to the recipient.
Please note that if you are using Syniverse's SPID, meaning you bought a Sender address from Syniverse, group messaging is currently only available in the US and on AT&T and Sprint only.
How to send a Group Message via SCG API.
With your application programmed with your Sender address, below is a sample message request to send a Group Message:
curl -X POST -H "Authorization: Bearer 8f8a41a5766eff1001a54e920d16f95" -H "Content-Type: application/json" -d '{"from":"EGec4ENUHMOf2AOSBGJek","to":["+14085551212","+19135551212", "+16695551212"],"body":"Hello World","group_mms":true}' https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests
It is important that the attribute "group_mms" is set to "true" to enable group messaging. For more information on Syniverse's messaging APIs, please visit our documents page at https://sdcdocumentation.syniverse.com/index.php/sms/resources
Note: As part of the MO messages, a .SMIL attachment is also sent. Depending on your application needs, you could ignore the SMIL attachment in your webhook configuration.
Sample MO Event for Group MMS
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"attachment_ids": "crXLv4gyFmMGNtWXNl6kL",
"mo_price": 0.015,
"message_id": "Kn5aJ5xS2X5pR4QBL5vXH4",
"to_address": "18327879821",
"has_attachment": true,
"application_id": 1714,
"sender_id_alias": "ljX2KJbs8zowzC8rFexzn6",
"company-id": 1500,
"sender_id_id": "ljX2KJbs8zowzC8rFexzo6",
"message_body": "Hello from Kola",
"group_to": "[\"+18138109839\",\"+18327879721\",\"+181339911=214\"]",
"fragments_count": 1,
"from_address": "+14086081111"
},
"evt-tp": "mo_message_received",
"timestamp": "2020-01-31T16:24:01.312Z"
},
"event-id": "hvM5462vS0WhaMHp2Wwifw"
}
View ArticleDepending on country specific regulations, in some cases virtual numbers require that users are located within the same region as the numbers you are leasing
It is essential that a valid business or residential address is provided during the purchasing of these virtual numbers. If the virtual numbers are intended to be used by an individual, the residential address of the end user should be provided. Virtual numbers purchased by a business entity should provide the registered address of the business.
There are 2 types of address requirements:
Requires an address from the same country as the number
Requires an address from the same region (City or State) as the number
In a few cases such as Hong Kong or Singapore, proof of address is also required when requesting a virtual number.
When purchasing virtual numbers with address requirements, Syniverse will require you to file a qualifying address with us before you are able to purchase the virtual number.
Country
Address
type required
Countries thatrequire
address when purchasing*
Countries where only
available on request
Proof of identity
required
Australia
Local Address
Yes
Bahrain
Country
Yes
Yes
Belgium
Local Address
Yes
China
Local address
Yes
Yes. Enterprise qualification documents needed. Selling only to enterprises.
Croatia
Local Address
Yes
Denmark
Country
Yes
France
Local Address
Yes
Germany
Local Address
Yes
Yes.Business registration certificate needed.
Hong Kong
Local Address
Yes
Yes
Ireland
Local Address
Yes
Italy
Local Address
Yes
Yes
Japan
City / Region
Yes
South Korea
Local Address
Yes
Latvia
Local Address
Yes
Netherlands
Local Address
Yes
Norway
Local Address
Yes
Panama
City
Yes
Portugal
City / Region
Yes
Singapore
Country
Yes
Slovenia
City / Region
Yes
Spain
City / Region
Yes
Sweden
City / Region
Yes
Switzerland
Local Address
Yes
Taiwan
Country
Yes
Yes. Business registration certificate needed.
Turkey
Local Address
Yes
United Kingdom
Country
Yes
*Buying numbers in these countries will be by request where your address will be required, and we will provide available virtual numbers to you once the request is approved.
Process for purchasing a virtual number
For countries where an address is required to purchase a number, Customer should contact Syniverse Customer Care support or their Account representative
For countries where you can request a number
If you are in a country such as Germany, Ireland, Hong Kong or Singapore, Syniverse has to provision the number to your account. Which means we request your address and consent to share your address with Suppliers and local regulators before adding the number to your account.
We will send the request to our Supplier to review and we will get in contact with you in case we require more information such as proof of address or personal identification as in some countries this is a requirement.
From here the team will add the number to your account and you will be notified to let you know you are all set.
Who uses the virtual number is important
If you own several virtual numbers for different customers in a particular country, we strongly encourage you to add multiple addresses - one for each customer in each Country. This is because regulators in countries with address requirements have the expectation that the address on file corresponds to the business or person who is receiving or originating calls from that number.
Using your own Telephone number as a Caller Line ID (CLI) for Outbound calls
Syniverse supports the functionality that allows Enterprise customers to use their own Telephone number as a Caller Line ID (CLI) for outbound calls. This number can be:
Regular Landline number
Toll-Free number
In both cases, the number must be an active number registered to the Enterprise. An active number is a number that can make and receive calls. The Enterprise must prove ownership of the number and be able to furnish a Local contact address including a name of an authorized user associated with the company and number. Number Spoofing is not supported.
Please note that while this can serve as an outbound calling ID, the number may also receive phone calls from your users. Incoming calls to this number will not be routed through Syniverse.
Additional charges may be required for provisioning of custom CLI.
View ArticleWhere supported, Syniverse Messaging customers can use Alpha senders as their messaging sender ID. In most cases, registration and approvals are required by the destination Operators. Please make sure to contact your Syniverse Implementation Manager or Sales representative if you wish to use an Alpha Sender.
To create an Alpha Sender ID via API
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name":"Kolanator Alpha Campaign","class_id":"COMMERCIAL","type_id":"SHORTCODE","address":"KOLANATOR","country":"USA","consent_managed_by":"USER","register_number":"false","capabilities":["SMS"],"billing":{"receipt": " Kola Receipt","expiration_date":"12.13.2028","company_name":"Kolanator, Inc","company_id":"55555","authorized_user":"Kola","phone":"+14086881111","email":"[email protected]","message_type":"SMS","description":" Messaging SC Production campaign ","shortcode_type":"ALPHA","campaign_type":"TRANSACTIONAL","campaign_website":"www.kolanator.com","campaign_discovery":"Website", "country":"USA","expected_date_of_service": "03.12.2019","use_case": "Alerts","estimated_volume":"1000000"}}'
View ArticleOur standard call rate is 1 CPS (Call per second)
View ArticleSend Message
ContentMessage
This identifies the content of a RCS message sent from the Business (Agent, ChatBot, Application) to an end-user. This attribute should be in the “body” field in SCG. A single request can include text, a rich card, an image, or a video as well as suggested replies and suggested actions. The maximum size of a message is 250KB
Parameter
Description
Suggestions [ ]
suggestionis an object that defines either anactionor areplyfor the RCS type. This is a list of suggested replies and suggested actions that appear as a list of suggestion chips following the associated message. The user can tap a suggested reply to send the text reply back to the agent or tap a suggested action to initiate a native action on the device. There is a Max 11 suggestion chips and a maximum of 25 characters for each suggested reply or action
Format: Object
Required:At least one oftext,media, orrichCardis required, UTF-8 encoding
text
Identifies the RCS message as an RCS text message.
Type:String, UTF-8
media
media is a file within a rich card. The media will have a height defined (enum), a filename (string) and contentInfo (Object)
richCard
Identifies the RCS as a Rich Card. A Rich Card is a small snippet, usually an image, that's linked to additional actions. For example, a Rich Card can be used to dial a phone number, access a website, or open a map. You can send multiple Rich Cards in a message.
Type:object
Required:At least one oftext,media, and/orrichCardis required. A richCard can be a Standalone card or carousel card
contentInfo
This carries information about a file, including URL of the file and the URL of the file’s thumbnail.
Type:object
Text
The simplest messages are made of text. Text messages are best suited to communicate information without the need for visuals, complex interaction, or response. Simple use cases like notifications, alerts or conversational chats can be composed in Text.
The Text parameter can be used within the contentMessage parameter.
curl -X POST "https://api.syniverse.com/scg-external-api/api/v1/messaging/messages
-H "Content-Type: application/json" \
-d "{
'contentMessage': {
'text': 'Hello, world!'
}
}"
SCG also supports simple composition of text messages using the "Body" parameter for RCS recipients similar to all other channels on the platform.
Sample Message:
curl -X POST
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages
-H 'Authorization: Bearer {TOKEN} \
-H 'Content-Type: application/json' \
-d '{"from":"sender_id:gtz9wXVkA51HSyB5wYTcP","to":"+14081111222","body":" Hello, this is my first text message to a RCS device"}
Field
Description
from
The “from” field includes the identifier that represents the customers verified identity
sender_id : This is a unique identifier that is provisioned for the customer’s RCS sender address. For more information on this, please see the API reference guide
Type: string for example : “sender_id:gtz9wXVkA51HSyB5wYTcP”
to
The “to” field is the parameter that identifies the address of the recipient(s). This is usually the mobile phone number of the recipient.
Type: E.164 format for example with US phone number +1-408-111-2222, the value would be “+14081112222”
body
The body field is the body of the message that contains the text message that the customer is sending to the recipient. The format is in UTF-8 encoding
ContentMessage
Customers can also compose a raw RCS text message using the contentMessage parameter as shown in the example below:
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer {TOKEN} \
-H 'Content-Type: application/json' \
-d '{
"from": "gtz9wXVkA51HSyB5wYTcP","to": "+14086270435","body":"{\"contentMessage\":{\"text\":\"Hello, this is my first RCS message!\"}"
}
Media
Themediatype further defines an RCS media message. For example, the RCS message might be a JPEGlinked to a website.
It's best practice to set contentMessage.forceRefresh to false. Setting contentMessage.forceRefresh to true forces the System to fetch new content from the specified URL, even if the URL content is cached, which increases message delivery times for users.
Note: To send message in raw RCS format, please set the Content_type parameter as below.
{“content_type":"application/vnd.scg.grcs.raw-message”}
Parameter
Description
fileUrl
Link to a publicly reachable URL of a media file. The full path must be used. The URLmust usehttps://and must link to a media file in.
Type:string
Required:Yes
mimeType
Indicates the type of media file. For example, this might beimage/jpeg.
Type:string
Required:Yes
fileSize
The size of the media file, in bytes. Different mobile operators have different size limits. For example, you might have a JPEG that is12367bytes.
Type:integer
Required:Yes. The maximum file size can be no more than 100 mb.
thumbnailURL
The URLto the image thumbnail, if a thumbnail is used. The full path must be used, starting with https://.
Type:string
Required:No
thumbnailMimeType
The image mime type. For example, this might beimage/jpeg.
Type:string
Required:Yes, but only if included the thumbnailURL. Otherwise, no.
thumbnailFileSize
The size of the thumbnail image file, in bytes. Different mobile operators have different size limits. For example, you might have JPEG that is125bytes.
Type:integer
Required:Yes, but only if you included the thumbnailURL. Otherwise, no. The maximum size of he thumbnail can be no more than 10 kb.
suggestions
Array ofsuggestionobjects. For example, this could be a link to a website or to place a call. The order of the list of suggestions is determined by their placement in the JSON request. In addition, suggestions formediaonly appear ifmediais the last item on the screen.
Type:collection
Required:No
Example:
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages
-H 'Authorization: Bearer [TOKEN} \
-H 'Content-Type: application/json' \
-d '{
"from": "gtz9wXVkA51HSyB5wYTcP",
"to": ["+18131234567"],
"content_type": "application/vnd.scg.grcs.raw-message",
"body":""{
'contentMessage': {
'contentInfo': {
'fileUrl': 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif',
'forceRefresh': false
}
}
}"
Suggestion
A suggested reply or a suggested action included within a rich card or within a suggestion chip list.
Parameter
Description
reply
SuggestedReply: User can tap a suggested reply to send the text reply back to the application, chatbot or agent
Type:String
text Text that is shown in the suggested reply and sent back to the application when the user taps it. Max 25 characters. We recommend not exceeding 10 characters for optimal user experience
postbackData- The is a based64-encoded playload that the agent receives as a MO event when the user taps the suggested reply
action
SuggestedAction: User can tap a suggested reply to initiate a corresponding native action on a device
text - Text that is shown in the suggested reply and sent back to the application when the user taps it. Max 25 characters. We recommend not exceeding 10 characters for optimal user experience
postbackData- The is a based64-encoded playload that the agent receives as a MO event when the user taps the suggested action
The native action initiated on the device when the user taps the suggested actionactioncan be only one of the following:
openUrlAction- Opens the user's default web browser app to the given URL. If the user has an app installed that is registered as the default handler for the URL, then this app will be opened instead, and its icon will be used in the suggested action UI. The URLmust begin with either http:// or https://
dialAction- Opens the user’s default dialer app with the application/agent specific phone number filled in. Use an alphanumeric source address using the international E.164 format; <country code> followed by the <national number>. For example,+12223334444.
viewlocationAction- Opens the user's default map app and selects the agent-specified location or searches around the user's location given an agent/application-specified query
Additional fields:
longitude: It must be in the range [-180.0, +180.0].
latitude: It must be in the range [-90.0, +90.0].
createCalendarEventAction- Opens the user's default calendar app and starts the new calendar event flow with the agent/application-specified event data pre-filled.
Additional Fields:
startTime: Event start time. A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example:"2014-10-02T15:01:23.045123456Z".
endTime: Event end time. A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example:"2014-10-02T15:01:23.045123456Z".
title: Event title.
description: Event description
shareLocationAction- Opens the RCS app's location chooser so the user can pick a location to send to the agent or application
RichCard
TherichCardmedia type defines one or more "cards" that display on the recipient's handset. These cards can then be associated with actions, such as dialing a phone number, pinning a map location, or accessing a website.
Rich cards can contain the following items:
Image/video
Title text
Description text
A list of suggested replies and suggested actions (maximum 4)
Parameter
Description
cardOrientation
Sets how a rich card is oriented.cardOrientationis used only when a single Rich Card is sent.
Type:string
Required:No. However, if passed,cardOrientationmust be one of the following:
HORIZONTAL
VERTICAL
imageAlignment
Indicates an image on a Rich Card.imageAlignmentis used only when a single Rich Card is sent.
Type:string
Required:No. However, if passed,imageAlignmentmust be one of the following:
LEFT
RIGHT
cardHeight
The height of a card when used when a single Rich Card is sent or the height of all Carousel Cards.
Type:string
Required:No. However, if passed,cardHeightmust be one of the following:
SHORT : 112 DP
MEDIUM: 168 DP
TALL: 264 DP (Not available for rich card carousels when the card width is set to small)
Cards expand vertically to fit their contents. Rich cards have a minimum height of 112DP and a maximum height of 344DP. If the contents of a card are not large enough to fill the minimum card height, the card expands and fills the extra height with white space
cardWidth
The width applied to all cards in a Carousel.
Type:string
Required:No. However, if passed, thecardWidthmust be one of the following:
SMALL
MEDIUM
cards
Defines the cards in an array. A single card is treated as a single Rich Card. Multiple cards are treated as a Carousel. Seecard below for more info
Note:There must be at least onecardin this array.
Type:card
Required:Yes
Card
cardcontains the information for a single card, such as specifying a graphic for the card, an action to take when clicking the card, and the descriptive text that appears on the card.
Parameter
Description
title
Text that displays on the card.
Type:string
Required:No. However, if used, you must use UTF-8 encoding. The maximum size of the title should be no more than 4096 bytes.
description
Descriptive text that appears on the card.
Type:string
Required:At least one ofdescription,media, orsuggestionsis required, but any combination of these three is valid.
media
Defines media, such as graphics, that you want to display in a card. For example, this might be an image with a linked URL.
Type:object
Required:At least one ofdescription,media, orsuggestionsis required, but any combination of these three is valid.
suggestions
Array that ofsuggestionobjects. For example, this might be opening a website or dialing a phone number.
Type:array
Required:At least one ofdescription,media, orsuggestionsis required. Any combination of these three is valid; however, the maximum number of suggestions for a single richCard is 4 for example, this might have three replies, three actions, or two actions and one suggestion. A maximum of 2 suggestions is allowed for each card in a carousel. See "cardHeight" belowfor information about carousel cards.
Media
mediadefines thecardassociated with the Rich Card. This might include displaying the Rich Card with a graphic.
Parameter
Description
fileUrl
Publicly reachable link to a media file. The full path must be used. The URLmust usehttps://and must link to a media file.
Type:string
Required:Yes
mimeType
Indicates the type of media file. For example, this might beimage/jpeg.
Type:string
Required:Yes
fileSize
The size of the media file, in bytes. Different mobile operators have different size limits. For example, you might have a JPEG that is12367bytes.
Type:integer
Required:Yes
thumbnailUrl
The Publicly reachable URLto the image and video thumbnails only, if a thumbnail is used. The full path must be used, starting with https://.
Type:string
Required:No
thumbnailImageAlignment
The image mime type. For example, this might beimage/jpeg.
Type:string
Required:No
thumbnailMimeType
The image mime type. For example, this might be image/jpeg.
Type: string
Required: Yes, but only if the thumbnailURL is included. Otherwise, no.
thumbnailFileSize
The size of the thumbnail image file, in bytes. Different mobile operators have different size limits. For example, you might have a JPEGthat is125bytes.
Type:integer
Required:Yes
suggestions
Array of suggestion objects. For example, this could be a link to a website or to place a call. The order of the list of suggestions is determined by their placement in the JSON request. In addition, suggestions for media only appear if media is the last item on the screen.
Type: collection
Required: No
-d "{
'contentMessage': {
'richCard': {
'carouselCard': {
'cardWidth':'MEDIUM',
'cardContents': [
{
'title':'Card #1',
'description':'The description for card #1',
'suggestions': [
{
'reply': {
'text':'Card #1',
'postbackData':'card_1'
}
}
],
'media': {
'height':'MEDIUM',
'contentInfo': {
'fileUrl':'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg',
'forceRefresh':false
}
}
},
{
'title':'Card #2',
'description':'The description for card #2',
'suggestions': [
{
'reply': {
'text':'Card #2',
'postbackData':'card_2'
}
}
],
'media': {
'height':'MEDIUM',
'contentInfo': {
'fileUrl':'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg',
'forceRefresh':false
}
}
}
]
}
}
}
}"
suggestion
suggestionis an object that defines either anactionor areplyfor the RCS type.
Parameter
Description
action
Defines the action to take for the click action. Each possible action is composed of further information, dependent on the action taken.
Type:object
Required:A suggestion must have either anactionor areply, but at least one.
reply
Defines the reply. See reply below for more information.
Type:object
Required:A suggestion must have either anactionor areply, but at least one.
Example usage
-d "{
'contentMessage': {
'text': 'Hello, world!',
'suggestions': [
{
reply: {
'text': 'Suggestion #1',
'postbackData': 'suggestion_1',
},
},
{
reply: {
'text': 'Suggestion #2',
'postbackData': 'suggestion_2',
},
}
]
}
}"
reply
Areplyprompts the recipient with display text to perform the requested suggestion.
Parameter
Description
Text
The text displayed to the recipient when the "suggestion" is a reply.
Type:string
Required:Yes. The maximum number of characters, including white spaces, is 25. We recommend that you use no more than 10 characters as a larger number requires the end user to scroll through the text to read the entire text.
postbackData
When passed in a request, this parameter allows information about the tapped reply to be returned to you as an MO event that the specific reply was tapped. This MO eventcan include additional information about the customer, such as a Phone number. For example, a reply might be an option to dial a phone number.
The parameter should be unique for each reply if multiple reply suggestions are included.
Type:string. If you want the response returned as JSON, you must escape quotes with \". For example,"postbackData:" { \"phoneNumber\":\"14085551234\"}".
Required:No. However, if this parameter is not passed no information is returned to you.
Example usage
{
reply: {
'text': 'Call',
'postbackData': 'suggestion_1',
},
action
Defines the action to take when the user clicks a media type if an action is defined for suggestions.
Parameter
Description
Text
Displays the text the recipient sees for that action. For example, this might be "Contact us!"or "Reply now".
Type:string
Required:Yes. The maximum number of characters, including white spaces, is 25. We recommend that you use no more than 10 characters as a larger number would require the end user to scroll through the text to read the entire text.
postbackData
When passed in a request, this parameter allows information about the tapped action to be returned to you as an MO event that the specific action was tapped. This MOevent can include additional information about the customer, such as an MSISDN. The parameter should be unique for each action if multiple action suggestions are included.
Type:string. If you want the response returned as JSON, you must escape quotes with \". For example,"postpbackData:"{\"UserClickWebsite\"}".
Required:No. However, if this parameter is not passed no information is returned to you.
Example usage
-d "{
'contentMessage': {
'text': 'Hello, world!',
'suggestions': [
{
'action': {
'text': 'Call',
'postbackData': 'postback_data_1234',
'dialAction': {
'phoneNumber': '+15556667777'
}
}
}
]
}
}"
Usage Example with Combination of Contents
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
"from": "SilzjFK6CBBmgFUBaYVWJ",
"to": "+14085551222",
"content_type": "application/vnd.scg.grcs.raw-message",
"body":"{\"contentMessage\":{\"richCard\":{\"standaloneCard\":{\"cardOrientation\":\"VERTICAL\",\"thumbnailImageAlignment\":\"LEFT\",\"cardContent\":{\"suggestions\":[{\"reply\":{\"text\":\"More info\",\"postbackData\":\"replied-more-info\"}},{\"reply\":{\"text\":\"Sign me Up!\",\"postbackData\":\"replied-Sign-me-up\"}},{\"action\":{\"text\":\"Visit Barcelona\",\"postbackData\":\"action-openurl\",\"openUrlAction\":{\"url\":\"https://www.barcelona.com/barcelona_city_guide\"}}},{\"action\":{\"text\":\"View direction\",\"postbackData\":\"location\",\"viewLocationAction\":{\"latLong\":{\"latitude\":\"37.2779914\",\"longitude\":\"-121.8890323\"},\"label\":\"Optima Dental\"}}}],\"title\":\"Barcelona in the Summer!!\",\"description\":\" Visiting Barcelona? Book the best tours and activities for the best price! Incredible experiences. Flexible booking. Over 40,000 activities. Easy online booking. Easy price comparison. No cancellation fees. Top attraction tickets. \n \n Plan your trip \",\"media\":{\"height\":\"MEDIUM\",\"contentInfo\":{\"fileUrl\":\"https://www.ciee.org/sites/default/files/content/program/main-image/hero_spain_barcelona_1600x1000_02_0_0.jpg\"}}}}}}}"
}'
SMS Fallback
When used, theFailoverparameter sends a fallback SMS message in the event the end user's phone does not support RCS. You must be provisioned to use this account and have a private channel created. For more information on Private channel, visit our knowledge base.
Note:UTF-8 is the only supported character set for an SMSfallback. If your message content is greater than the supported number of characters, your message will be split into multiple fragments using the SCG Messaging API. Your carrier may charge you for each sent fragment.
Sample
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
"from": "channel:leMXuQrmJ3dcR2OE7q4BV2",
"to": "18005551212",
"failover": "SMS",
"contact_delivery_address_priority": ["RCS"],
"sender_id_sort_criteria": ["DELIVERY_ADDRESS"],
"body": "fallback to NON rcs capable device"
}
ESS Events and MO content type changes
New topic added - “SCG-Chat”.
New event in added in topic “SCG-Chat” - “typing”. The event indicates that the remote party is typing within the chat window of the RCS agent represented by the corresponding sender id.
{"evt-tp":"typing","fld-val-list":{"sender_id_alias":"XlmTargEIStVGU4kXlDFQ6","sender_id_id":"XlmTargEIStVGU4kXlDFQ6","company_id":99999,"to_address":" +359886178558@softaval-rcs-project-for-scg.iam.gserviceaccount.com ","from_address":"+359888121204","application_id":536,"timestamp":"2018-12-20T17:12:03.281987Z"}}
Content Type "application/vnd.scg.location"
This new content type defined for MO message and events indicate that the body of the message contains location coordinates following this example:
"longitude: 23.3891704, latitude: 42.6561869"
Content Type "application/vnd.scg.grcs.suggestion-response"
This new content type defined for MO message and events indicate that the body of the message contains stringified JSON of the RCS specific suggestion response, like this:
"{\"postbackData\":\"replied-no-no\",\"text\":\"no, no, thanks\"}"
Parsed as JSON this will render the reply chosen by the user and the corresponding postback data associated with this reply in the suggestions section of the MT message.
View ArticleMessaging
1. SCG API Error codes
Error Code
Error Description
Http Code
400
Bad Request
400
400
Constraint violations: <field> is required
400
400
Language <language> not found
400
400
Cannot include media URLs with attachment
400
400
Cannot exceed more than 5 media URLs
400
401
Unauthorized
401
402
Insufficient credit
402
403
Forbidden
403
403
Bad SAOP Context
403
403
Attachment <id> is in incorrect state <state>
403
403
Invalid sender ID state: <state>
403
403
Invalid sender ID ownership: <ownership>
403
403
SenderId start date in the future: <date>
403
403
SenderId end date in the past: <date>
403
403
The specified app does not support <token>
403
403
Load content forbidden for attachment in state: <state>
403
403
<operation> forbidden for role: <role>
403
403
<operation> forbidden for channel with ownership: <ownership>
403
403
Operation forbidden for sender ID with ownership: <ownership>
403
403
User managed consent forbidden for sender ID: <id>
403
403
User managed delete of consent forbidden for sender ID: <id>
403
403
Operation forbidden for SenderId with type: <type>
403
403
User managed delete of consent forbidden for sender ID: <id>
403
403
SenderId does not support <provider>
403
403
Cannot set criteria for group type <type>
403
403
Cannot add contacts to dynamic group
403
403
Cannot remove contacts from dynamic group
403
403
State transition <old state> -> <new state> forbidden for <MT/MO> messages
403
403
Only admin can create numbers import job
403
403
Only admin can create purge customer data job
403
403
data_types cannot be empty list
403
404
Not Found
404
404
Sender ID not found for alias <alias>
404
409
Conflict
409
422
Unprocessable Entity
422
500
Server Error
500
503
Service Unavailable
503
1020
The Tracking URL <url> failed verification as a valid URL
400
2. SCG Failure Errors
Failure Code
Failure Details
1001
Stale data
1002
Invalid Recipient
1003
No Applicable Sender ID
1004
Forbidden Phrase
1005
No Consent
1006
Could not find template with name <name>
1006
Template config mismatch between channel and senderId
1006
Message does not satisfy any of the senderId validators
1006
Message does not satisfy any of the channel validators
1006
No value provided for variable: <variable>
1006
Validator rule <rule> failed on <variable>:<value>
1006
Validator rule <rule> failed on <message>
1007
Message Expired
1008
Whitelist Violation
1009
Delivery Failure
1010
Content refused, type <mimetype>, allowed: <mimetype>, blocked: <mimetype>
1011
Duplicate key
1012
Message size <size> exceeds max allowed size <size>
1014
Message encoding failed, tried: <encoding>
1015
Invalid sender address
1016
Invalid/illegal character in url: <character>
1017
Invalid Dynamic Group definition
1018
Message assembly failure
1019
Attachment size <size> exceeds max allowed attachment size <size>
1020
Invalid Tracking URL
1021
Invalid sender address credentials
1022
Failed price threshold. Unknown price.
1022
Failed price threshold - current price <price>, price threshold <price>
1023
Indexed field too long
1024
Translate failed
1025
Invalid social handle
1026
Too many recipients
1027
No Sender ID suitable for auto purchase
1028
Storage quota exceeded
1029
Contacts quota exceeded
1030
Too many recipients in one batch
1031
Illegal SMTP header value
1032
Invalid registered delivery flag
1033
System error from remote service
1034
Invalid service type
1035
Command length is invalid
1036
Wrong state for command
1037
Invalid message id
1038
Outgoing queue is full
1039
Throttling error
1040
Invalid scheduled delivery time
1041
Submitting message has failed
1042
Invalid source address type of number
1043
Invalid destination address type of number
1044
Invalid number of messages
1045
Invalid Validity Period
1046
Message was rejected
1047
Permission denied
1048
Invalid data coding scheme
1049
Invalid request
1050
Multiple addresses not supported
1051
Validation error
1053
Failed to upload media URL
1054
Failed to download media URL
Voice Calling
1. Voice Calling API Errors
Error Code
Error Description
Http Code
403
No admin access to this API
403
403
Access denied for sender ID: <id>
403
403
Forbidden access to call service maintenance.
403
2. Voice Calling Failure Errors
Failure Code
Failure Details
1052
Invalid call state <state>
1201
No answer
1202
Call rejected
1203
Temporary failure reaching recipient
1204
Recipient busy
1205
Invalid phone number quantity
1206
Phone number doesn't exist
1207
Failed to delete the phone number
1208
Call id not found
1209
Recording is already started
A2P SMS Failure Errors
SCG Error Code
SCG Error Description
1002
Invalid Recipient
1015
Invalid sender address
1038
Outgoing queue is full
1039
Throttling error
503
Service Unavailable
1046
Message was rejected
1012
Message Too big
1035
Command length is invalid
1036
Wrong state for command
1037
Invalid message id
1040
Invalid scheduled delivery time
1032
Invalid registered delivery flag
1033
System error from remote service
1034
Invalid service type
1026
Too many recipients
1041
Submitting message has failed
1042
Invalid source address type of number
1042
Invalid source address type of number
1043
Invalid destination address type of number
1043
Invalid destination address type of number
1044
Invalid number of messages
1045
Invalid Validity Period
1009
Delivery Failure
1047
Permission denied
1047
Permission denied
1047
Permission denied
1048
Invalid data coding scheme
402
Insufficient credit
A2P MMS Errors
SCG MMS Error Code
SCG Error Description
1015
Invalid sender address
1015
Invalid sender address
1010
Content Refused
1012
Message Too big
503
Service Unavailable
1049
Invalid request
1047
Permission denied
1046
Message was rejected
1050
Multiple addresses not supported
1041
Submitting message has failed
1051
Validation error
P2P MMS Errors
SCG MMS Error Code
SCG Error Description
1002
Invalid Recipient
503
Service Unavailable
500
Server Error
Facebook Messenger Errors
SCG FB Error Code
SCG Error Description
1012
Message Too big
1002
Invalid Recipient
1002
Invalid Recipient
400
Bad Request
View ArticleQuick Start guide to using the SCG Voice & Messaging Service.
To get started, please read and familiarize yourself with the Voice and Messaging Service offering user guide and API resource documents. Both documents are available and can be accessed under the documents menu.
Once registration is completed through the SDC (Syniverse Developer Community) portal and you are automatically subscribed to the Voice and Messaging service offering. Next step is to configure your application and payment account.
Now you are ready to send your first SMS message.
Syniverse Communication Gateway offers APIs for sending and receiving messages over SMS, MMS, Social Messaging services (Facebook Messenger & WeChat), RCS and Push Notification services.
Sending a SMS or MMS MT (Mobile Termination) Message via API or UI
Sending a SMS MT (Mobile Termination) Message
To send a SMS message to a recipient via the SMS API, you will need the following:
Base URL: https://api.syniverse.com/scg-external-api/api/v1
A Channel ID or a Sender ID. SCG provides a Test Channel ID for your convenience.
A recipient number in E164 format. ( If using a trial account and the recipient number is a US Mobile number, you will need to whitelist this number)
Bearer Token: This is your Access token that is generated with your registered application.
Using your application, POST a message request to the provided base URL using the sample CURL below:
Syniverse has provided you with a Public US Test Channel, Channel ID = 1KJPMkuHQkair_o15etpmg
Request:
curl -X POST -H "Authorization: Bearer [Access Token]" -H "Content-Type: application/json" -d '{"from":"channel: 1KJPMkuHQkair_o15etpmg ","to":["+14082225555"],"body":"Hello from SCG message"}' https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests
Response:
"id": "SJciWWUnfw369P9KyTnkJ2"
Python Sample Code snippet to send a SMS
import requests
url = "<a rel="nofollow" target="_blank" href="https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests">https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests</a>"
payload = "{\"from\":\"channel:1KJPMkuHQkair_o15etpmg\",\"to\":[\"+14082225555\"],\"body\":\"Hello this is my first message\"}"
headers = {
'authorization': "Bearer 3c5a336df4d9d3f3e4d129a755b0f377",
'content-type': "application/json",
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.status_code)
print(response.text)
For sample libraries and cURLs to get you started, visit our repositories here
Optionally, you can also access the Voice & Messaging Offering GUI application for a visual function of the APIs
The SCG UI dashboard includes the following Menu structure:
Sending Messages via UI
Select Messaging and click on “ Send Message”
If you are sending a SMS, make sure the SMS tab is selected and input your parameters.
Select a Sender ID or Channel you wish to Send from
Input a mobile number ( International format) or select from a contact list or Contact group
Select the appropriate template if sending from Syniverse public channel or Sender ID otherwise input you message in the Message box
Click Send or Cancel.
View Status of Sent Message in UI
Select “Outbox” under the Message tab
View your message details in the window. Double-Click Message to get more details
View Received Messages
Select “INBOX” under the message tab
View messages in your inbox.latest messages is usually on top
Click message for more details.
Receiving a SMS MO (Mobile Originated) message in your Application
To receive SMS messages sent to your application from a mobile phone number, you will need the following:
Purchase a Dedicated Sender Address: This is a unique identifier to which a user can sender you a message. For more info on Sender Address, please check out the SCG user guide. To Purchase a Dedicated Sender Address to use for your application, please refer to the " How to Purchase a Sender ID on SCG " article. Please note that a payment account is required to purchase a dedicated Sender address. Your Trial account cannot be used to purchase a Sender Address.
A subscription to Events Manager: This is a Callback service where all the events including MO messages destined for your application is POST to your application.For more info on how to subscribe and setup your application to receive status events, please visit the SMS/MMS user guide here
Setting up a Payment Account
Postpaid Account
NOTE: It is recommended you work directly with a Syniverse representative when setting up a postpaid account.
While logged in, navigate to the Company menu by clicking on account name on the far right corner of the portal
Select theAccountstab
Click on the "Request Postpaid Account" button
Give the Account a name
Select if you want to have a Restricted account (only users with specific entitlements can access this account)
Enter First Name and Last name
Enter Email Address
Enter your Company's contact Phone number
Make sure the Company name is the same as in the Tax ID records
Enter a valid Federal TaxID
Enter billing address that matches Tax ID information
Select the “I already have a Syniverse BillingID “ if you’ve already been provisioned for one
Enter the Billing ID
Read and Accept the Terms of Service
Click Submit. This will be in a pending state till all approvals are given.
View ArticleOverview
As an authorized RCS Business Messaging (RBM) Solution provider in partnership with Mobile Operators Syniverse has developed a solution to make it easy and economical for businesses to create and manage engagement with their customers using the RCS Business Messaging Channel.
This compelling new channel with access to users world-wide is now part of Syniverse’s cloud-based Omni-Channel messaging solution and with the same API endpoint that we offer for SMS, MMS, Facebook Messenger, Push Notification & WeChat, businesses can now add RCS as an engagement channel with very little work!
Syniverse will invite customers to participate in the Syniverse RBM early access preview program.
What can you do with the SCG RCS Business Channel?
Send and receive messages from to and from end-users with a verified Sender Address (Agent)
Engage your customers in a 24/7 customer care conversational messaging using a Chatbot or with a live agent on Syniverse 2-way Chat application**
Send Template messaging to your customers
Reach end-users world-wide where RCS is available
Trigger Fallback to SMS*
Translate your Messages into different languages
Schedule messages
Engage users on variety of use cases ranging from OTP, Critical Alert update, Payment update, Shipping update, Issue resolution, Reservation update etc.
Get real-time feedback on Messages status (is-typing, Delivery Receipts (Delivered, Read, Failed etc.)
*Channel resource required
** Available in Q1 2020
How it works
The Syniverse Omni-channel messaging solution provides a set of APIs for approved customers participating in the Syniverse RCS EAP (Early Access Preview) program to trigger their RBM Agent to establish RCS communication with end-users with RCS-capable/enabled devices. Below are the requirements for enabling a valid RCS service.
A Syniverse Omni-channel Messaging Account and service subscriptions
An approved RBM agent setup by Syniverse for the customers (see details below on the requirements for registering an RBM agent)
A Syniverse Sender ID for the RBM agent
An RCS-enabled messaging Test Device
Message Flow
Your Chatbot/application submits a request to the Syniverse omni-channel messaging service via a REST API using a Syniverse Sender ID. Please note that an external event must trigger the agent to send the first message to a device. A trigger can be anything and depends on your agent's use case. External triggers might include:
the user opted into shipping notifications and a package is delivered
the user opted into lunchtime sandwich deal notifications and the clock strikes noon
the user called customer support and chooses to continue the interaction via chat
Please note that as it is with guidelines around user privacy and consent, Syniverse and or its service partner may at anytime request a proof of user consent to receive an RCS message.
The Syniverse gateway triggers the RBM agent to initiate an RCS conversation with the end-users. The end-user can't start a conversation with your agent, but once the agent starts a conversation, the user can send a reply at any time
Once the trigger activates your agent, a capability request is sentto the end-user's device. If the device supports RCS, then Syniverse sends a message via your agent. If the device doesn't support RCS, the Syniverse can trigger a fall back to SMS if that functionality is enabled. Fallback may functionality requires additional service subscription
The end-user receives the message in an RCS-enabled messaging app on their device.
When the user responds to the message or triggers an event, the RCS app sends the response via Pull subscription service, which passes the information the Syniverse Event Manager. The Event Manager is where your webhook is configured.
The Event manager will POST all events/message to your application/chatbot. All user messages, events, and other requests to your Chatbot/Application as base64-encoded JSON.
Supplementary API Reference document
How to get started
To participate in the early access preview program or POC using the Syniverse RCS Business Messaging Channel, Customers will be required to complete an RCS participation request form or contact your Syniverse Sales representative. Once your request has been received and approved, your Sales Rep will discuss on-boarding options available Markets and use cases.
Sign up for Syniverse Omni-Channel Messaging Service
As a prerequisite for participating in the Syniverse RCS EAP program, Customers need to be subscribed to the Syniverse Omni-channel messaging service and execute a valid term of service agreement with Syniverse
Register for a Syniverse Service Account by accepting the online terms of service: https://developer.syniverse.com ( If you have an existing contract or an addendum, this is also valid for account set-up) https://sdcsupport.syniverse.com/hc/en-us/articles/216101408-Quick-Start
Create a Company within the Account and setup a payment account
Configure your Syniverse application to get your access token
Configure a webhook to get your events sent back to your application. Check out the article on how to setup a webhook here
Once your Syniverse account is completely setup, you can get familiar with Syniverse’s API documentation which can be found here.
Syniverse RCS EAP Program
Below is an outline of what is needed:
A valid RCS-Capable Syniverse Sender ID
An approved RBM (RCS Business Messaging) Test Agent
Test Devices (Please see a list of recommended Android devices below in the Appendix)
An approved Publicly available RBM Agent. This Agent is your publicly available RCS agent that anyone can discover. It will replace your Test Agent.
Public availability will require additional approval and subject to availability of RCS on Mobile Operators and Devices in the region you are looking to launch your program
Setting up a Syniverse RCS Sender ID
Once your Syniverse account has been setup and your application is ready to call the Syniverse Omni-channel Messaging APIs, one of the first things you will need is a RCS Sender ID. The RCS Sender ID is a unique identifier that help you trigger your RBM agent. RCS Business Messaging (RBM) agents communicate with end-users through messages, events, and requests for actions. The RBM agents will use a variety of tools (such as rich cards, media, and suggestions) to guide users through fluid conversations that satisfy user and their needs. Syniverse will create an RBM agent for you once your sender ID request has been received.
Registering for an RBM Agent
A critical part of the Sender ID process is the registration of an RBM agent for a specific RCS program the customer is looking to make available to their end-users.
To register RBM Agent, the following information needs to be submitted to your Syniverse Rep so that we can create your Syniverse RCS sender ID and an RBM Agent for your application/Chatbot.
Company Name
Authorized Name (First and Last name)
Authorized Email Address
Region of your bot (APAC, EMEA, AMERICAS, OTHER)
Service Agent Name
Service Agent Description
Color (format #AABBCC). Contrast ration must be at least 4.5 or above on white background
Primary Website
Label for primary website (25 Characters max)
Customer facing Primary phone number (E.164 format)
Label for the customer facing phone number e.g. Customer Service, Shipping (25 Characters max)
Customer facing Primary Email address (this is the email address that shows on your verified Sender ID)
A Logo image URL (224x224px JPEG, no larger than 50KB) for the agent's icon)
A Hero image URL ((1440x448px JPEG, no larger than 200KB) for the agent's banner)
Privacy policy URL
Terms of service URL
Once your Sender ID request and RCS Agent profile information has been received, Syniverse will process and apply for an RBM agent on your behalf. (Please note that approval from our Carrier partners could take up to 5 business days). Once approval of your RBM agent is received, your Syniverse RCS Sender ID will be activated, and you can now start testing RCS with an approved test device.
Please note that during this Phase, only Test devices can send and receive RCS messages. Syniverse will work with the Customer to enable them as a TO (Test Organization) so that they can configure test devices for testing. The configuration of test devices involves using a registered TO (Test Organization) email/password and provisioning of applications on the device. Syniverse will provide the necessary assistance to ensure proper configuration.
Once testing is completed, then customer is ready to launch publicly.
For additional information on how to create and submit a Sender ID, please see “Using SCG RCS APIs” section below
Using the SCG RCS APIs and Message Console
Create a Syniverse RCS Sender ID
via API
Request:
curl -X POST -H "Authorization: Bearer Token" -H "Content-Type: application/json" -d '{"name":"ACME RCS_Sender","class_id":"COMMERCIAL","type_id":"RCS","address":"[BLANK]","country":"USA", "consent_managed_by":"USER", "capabilities":["RCS"]} "billing":{"receipt": "ACME Company","expiration_date":"01.12.2023","company_name": "KOLANATOR,INC", "company_id": "1234","authorized_user":"James Smith","phone":"14085555555","email":"james.smith@acme","message_type":"RCS","description":"Customer service Chatbot", "campaign_type":"transactional","shortcode_type":"Random","campaign_website":"www.acme.com","campaign_discovery":"website"} ' https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids
via SCG Message Console
Response:
200, OK
{vAh0hCAVYX0VXTTLdL3sn3} Sender ID
Once the Request is submitted, it will be in “Pending Implementation” state until the RBM Agent registration is complete and provisioned.
To check the status of the Sender ID, you can run a GET command to the Sender ID resource using the sender ID received in the response above. This will let you know if your Sender ID is active
Request:
curl -X GET \
https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids/ vAh0hCAVYX0VXTTLdL3sn3 \
-H 'Authorization: Bearer Token' \
-H 'Content-Type: application/json' \
Response:
{
"list": [
{
"application_id": 16457,
"company_id": 131338,
"created_date": 1550191698465,
"last_updated_date": 1551725647502,
"version_number": 5,
"id": " vAh0hCAVYX0VXTTLdL3sn3",
"name": "Kolanator_RCS",
"ownership": "PRIVATE",
"class_id": "COMMERCIAL",
"type_id": "RCS",
"state": "ACTIVE",
"address": "716219596055",
"message_handler": "SCG_ESS",
"country": "USA",
"keep_sender_address": true,
"consent_managed_by": "NONE",
"applied_charges": [
],
"capabilities": [
"RCS"
],
"alias": "Kolanator"
}
],
"limit": 50,
"total": 1
}
Invite an RCS Tester
Once your Syniverse Sender ID is active, this means your Agent has been registered and approved. You can now Invite testers to your Agent. These testers can receive RCS messages from your Sender Address and send messages to your verified Sender address (Agent). All testers/devices must have been provisioned with your TO email address and be an RCS capable Android device on a participating Carrier. An error will be returned if you invite a user as a tester and they don’t have an RCS capable device or have not been provisioned with the TO email address.
Please note that iOS devices currently do not support RCS.
Request
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer Token' \
-H 'Content-Type: application/json' \
-d '{"from":"sender_id: vAh0hCAVYX0VXTTLdL3sn3","to":"+14081112222","content_type":"application/vnd.scg.tester-invitation","body":""}'
Sender_id: vAh0hCAVYX0VXTTLdL3sn3 (Unique ID for your Agent Sender address)
To: +14081112222 (Mobile number for the user you are inviting to be a tester)
Send a Rich Card with Suggested list
Sample Request:
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer Token' \
-H 'Content-Type: application/json' \
-d '{
"from": " vAh0hCAVYX0VXTTLdL3sn3",
"to": "+14081112222",
"content_type": "application/vnd.scg.grcs.raw-message",
"body": "{\"contentMessage\":{\"suggestions\":[{\"reply\":{\"text\":\"Nice\",\"postbackData\":\"replied-nice\"}},{\"reply\":{\"text\":\"no thanks\",\"postbackData\":\"replied-no-no\"}},{\"action\":{\"text\":\"Reservation\",\"postbackData\":\"action-openurl\",\"openUrlAction\":{\"url\":\"https://www.expedia.com/\"}}}],\"richCard\":{\"standaloneCard\":{\"cardOrientation\":\"HORIZONTAL\",\"thumbnailImageAlignment\":\"LEFT\",\"cardContent\":{\"title\":\"Barcelona\",\"description\":\" Visit Barcelona in spring!\",\"media\":{\"height\":\"HEIGHT_UNSPECIFIED\",\"contentInfo\":{\"fileUrl\":\"https://drive.dropbox.com/uc?id=1LydMWVi76QA4WSD5Ds1LHjvfH5tyusz55\"}}}}}}}"
}'
For Additional API reference, check out the for more information
Launching a Public RCS Business Messaging Service
Once you're done testing your agent and it's ready to interact with users, it's time to launch. This is phase is where your RBM agent is made public to all RCS-capable devices globally.
You will be required to submit a launch questionnaire and go through a review after which your RBM agent will be able to reach RCS-capable users around the world. Syniverse will require the Customer to complete the questionnaire below. Please note that the information below is required by our Carrier Partners to review and approve your agent for a public launch.
Customer Agent launch questionnaire
Once you are ready to launch your RBM agent publicly, send an email to your Syniverse Account Rep or Implementation Manager with answers to the questionnaire below. Please note that to avoid delays, all questions need to be answered completely.
1. Use case/Program brief
Describe in detail how you and/or the brand obtain user opt-in to be contacted by the agent. Include instructions to find and follow this flow if possible, or screenshots if reproducing is not possible.
Describe in detail how outbound messages from the agent will be triggered. Specifically address how the very first message from the agent to a user is triggered.
Describe in detail what types of interactions the agent will have with users. Including both primary interactions (those that occur most commonly) and secondary interactions (those that are possible but less common).
Does your agent supportSTOP reply from end-users?
2. Brand details
We'll need some information about the brand that is represented by the agent. This information may be shared with carriers for the purposes of receiving launch approval for the agent.
Legal company name
Organization type (choose one):
Registered corporation
Licensed professional
Franchise
Public utility
Government or state organization
Corporate registration number (optional)
Tax ID or FEIN (optional)
Primary company address or corporate headquarters
Online landing page/url
3. Rights to branding
Provide us with the exact branding that your agent will launch with. There will be some flexibility to update this in the future but doing so may incur delays. Specifically, you must provide
Name
Description
Logo image URL
Hero image URL
Provide us with proof of written consent of your right to use this exact branding for this RBM agent, granted by someone who has the right to delegate the use of that branding to you. For instance, an appropriate response would be a copy-and-pasted email from a marketing executive at the brand of the form:
"I,marketing exec,email address, grant[Syniverse]the right to create and operate an RBM agent using the following branding:name,description,logo image,hero image."
4. Terms of service and privacy policy
Provide us with a link to the agent's terms of service and privacy policy, or with the document files themselves. When the agent launches, these documents will be made accessible to end-users from the agent's business information page. This will be reviewed by our legal team prior to launch.
5. Traffic estimate
Assuming every person in the US is RBM-reachable (including Android and iOS), estimate the messaging traffic the agent will require, both outbound and inbound. For example, 10K users reached by the campaign, an average of 7 messages exchanged per user per month.
Assuming every person in the US is RBM-reachable (including Android and iOS), estimate the agent's maximum outbound messaging QPS. For example, maximum throughput of 2K outgoing and 1K incoming messages between the hours of 12pm and 1pm on Tuesdays.
View ArticleThis solution is an example of a Voice services solution that is powered by the SCG communication Assistant application.
Solution Overview
In recent years Business have found themselves with the challenge of taking advantage of the digital transformation that is impacting commerce and consumer engagement and having to balance this with providing adequate security to safe guard their systems and consumer data and privacy. In solving this challenge, it has become critical for Businesses to be able to accurately authenticate and verify users that are accessing business systems to ensure they are authorized to do so. One of the most common methods of doing this is the use of 2FA (2- factor authentication) which comprises of a knowledge based factor ( e.g user name, password, account number) and a possession based factor (e,g mobile phone/number, token, fingerprint, retina etc).
To provide an easy yet powerful way for Businesses to quickly add a secure verification solution to their applications, Syniverse has developed a voice-based solution powered by SCG Communication assistant IVR application that integrates dtmf (digit collection) and Speech to text* for user passcode verification purposes as one of the possession factor in a 2FA solution.
Solution Use case
Customer generated token or Syniverse customizable token generation, user validation and verification (Optional)
Verification of generated token via dtmf ( digit collector ) or Voice confirmation using outbound calling
Verification/Validation confirmation events posted to business application
Benefits of a Voice-based Verification solution
Cost effective and easy to use application, saving time-to market & development time
Voice-based IVR solution with support for mobile or landline calling
Customizable XML script and call recording template for outbound call or text to speech
Solution setup guide:
There are a few options when considering using the Programmable Voice Solution, we recommend talking to a Syniverse expert to assist you with choosing the best option for your application.
What you will need:
A SDC ( Syniverse Developer Community ) account
Subscription to a Voice Calling API service offering from the SDC portal
Solution option ( A Syniverse sales expert can assist you with option, terms and pricing)
How it works
Upload customizable script
curl -X POST <a href="https://api.syniverse.com/scg-external-api/api/v1/assistant/communication_applications/applications/scripts">
-H 'authorization: Bearer 8f8a41a9766eff1641a54e920d16f95'
-H 'cache-control: no-cache' -H 'content-type: application/json'
-d '{ "name":"pmt_05037", "description":"IVR script Syniverse-1",
"body": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><ivr id=\"2\" description=\"kongo flow\" initialStep=\"welcome\" interDigitTimeout=\"15\" maxDigits=\"1\" maxConsecutiveIterations=\"3\" voice=\"bridget\"><step name=\"welcome\" type=\"announce\" prompt=\"Hello. This is a message from the Company Security Team.\">
<choice next=\"pinValidation\"/></step><step name=\"pinValidation\" type=\"gather\" prompt=\"Please enter the pin that is shown on your Screen.\" maxDigits=\"8\" minDigits=\"1\" maxConsecutiveIterations=\"3\" interDigitTimeout=\"10\">
<choice next=\"processValidation\"/></step><step name=\"processValidation\" type=\"announce\" prompt=\"Validating Pin. Please wait\"><processor id=\"pinValidation\" event=\"processor_event:processor_id={id};digits={digits};session_id={session};call_id={callId}\">
<timeout seconds=\"120\" next=\"invalidPin\"/></processor></step><step name=\"postValidationSuccess\" type=\"announce\" prompt=\"The Pin has been validated Successfully.\"><choice next=\"hangup\"/></step><step name=\"invalidPin\" type=\"gather\" prompt=\"The pin that was entered is not valid. Press 1 to re-enter the pin.\"><choice next=\"pinReValidation\" digit=\"1\" maxDigits=\"1\"/><choice next=\"hangup\"/></step><step name=\"pinReValidation\" type=\"gather\" prompt=\"Please enter the Pin that is shown on your screen.\" maxDigits=\"6\" maxConsecutiveIterations=\"1\"><choice next=\"processValidation\"/></step><step name=\"hangup\" type=\"hangup\" prompt=\"Goodbye and Have a nice day\"/></ivr>"}'
Create Instance
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/assistant/communication_applications/instances \
-H 'authorization: Bearer 8f8a41a5796eff1641a54e920d16f95' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"sender_id":["il4eAFkYQiRcCesfDHyIQ"],
"script_id":"3PBalxNKF4PFGmggLYWqp2",
"allow_incoming_call": true,
"state":"ENABLED"
}'
Create IVR Session
curl -X POST https://api.syniverse.com/scg-external-api/api/v1/assistant/communication_applications/instances/BnwSgTjld4FwrdlUJEudw6/sessions -H 'authorization: Bearer 8f8a41a5796eff1641a54e920d16f95' -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{"to_address":"+14085551212","state":"ACTIVE"}'
#Post processor Event to IVR
Success
curl -X POST https://api.syniverse.com/scg-external-api/api/v1/assistant/communication_applications/instances/BnwSgTjld4FwrdlUJEudw6/sessions/u54pcNPxDN4h2OOLMNvE2/processor_results -H 'authorization: Bearer 8f8a41a5766eff1641a54e920d16f95' -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{"call_id":"iNyp82XPaaA9Ue8rWNlBh","processor_id":"pinValidation","next_step":"postValidationSuccess
View ArticleCLI:
Local Korean numbers as CLI are forbidden to be used to send traffic towards South Korea.
In South Korea, it is not allowed to add “+” sign
When you call from overseas, caller should see int’l telephony carrier’s prefix + calling number
e;g Prefix for different Carriers(KT 001 / LGU 002 / SK Telink 006)
View ArticleOther features/restrictions of note:
Inbound Voice: Virtual Number Regulations and Compliance
If you are handling call center activity/traffic, either directly or indirectly, please be aware of the following regulations imposed by the local Italian regulatory agency.
You must inform the calling customer of the location of the call center operator or agent who is answering. In the event that this agent it not located in an EU country, it must be possible for the customer to have their call directed immediately to an agent located in a country who is a member of the EU.
View ArticleOther features/restrictions of note:
Virtual numbers:
TTS use cases are currently not supported on our LVN Landline numbers.
View ArticleChinese carriers have strict requirements to allow Voice traffic into their networks.
Nexmo is able to provide voice termination into China, however, this requires a pre-registration process, currently restricted to managed accounts only.
CLI:
Once an account gets pre-registered, calls will be sent from an international, non-China number when using our Voice products.Our product does offer CLI delivery for calls delivered from international numbers (in international format), but not from China numbers in international format (e.g. 86XXXXXXXXXXX). If you require to use your own international CLI, please contact your account manager to get this set up for you.
Content:
Chinese Carriers do not allow marketing calls. Any such traffic will be blocked at the request of the Carrier without warning. Our voice routes to Chinacannot terminate Call Center originated traffic either.
View ArticleCLI:
Our Voice products do offer CLI/Caller ID delivery for calls delivered from international numbers in international format, but not from Japan numbers in international or national format (e.g. 81701167890, 70xxxxxxxx/ 80xxxxxxxx/ 90xxxxxxxx ). The calls will still succeed, but the Caller ID will be stripped or changed.
View ArticleOther features/restrictions of note:
When placing calls to any recipient using the Syniverse platform, you will need to ensure the phone number is formatted correctly.
For mobile recipients, you must add a "9" to the number after the country code, i.e. 5491123452345. Without this the calls to mobile numbers will fail with a SIP response of 404, 484 or 500 depending on the network.
The "9"must notbe inserted for calls to land line recipients, or the call will fail .
View ArticleOverview
To get started, please read and familiarize yourself with the SMFA (Syniverse Multi-factor Authentication) Service offering Overview guide and API resource documents. Both Documents are available in the SDC portal and can be accessed under the Documents menu.
Once registration is completed through the SDC (Syniverse Developer Community) portal, login to SDC.
After login, proceed to subscribe to the SMFA service offering by following the instructions below:
Click
Click Multi-Factor Authentication Service Offering
Expand "Subscriptions" menu
Click "Subscribe..." and select "Initial account for [Your username]"
Accept Terms of Service
Click
Verify that your "Initial account for [Your username]" is listed in Subscriptions
Click
Click
Give your Application a name and description, Click Save
Click icon next to your app name and select "Edit"
Expand "Account & APIs" menu
Select the "Initial account for [Your username]" from drop down menu
Turn "SMFA" and "Whitelisting Services" On
Expand "Auth Keys"
You can Re-Generate the Access token (optional)
Copy and store keys in a safe place
Click "Save"
Hover over "Your Name" on top right corner
Click "Company"
You can give your Company a name (Optional)
Scroll down and Click tab (Whitelisting is required for the numbers you intend to send to using the Initial Account)
Click "Add phone number"
Enter your mobile number and click "Send confirmation code"
Enter the code you received as an SMS
Click "Add"
Now you are ready to use the MFA service.
Syniverse Multi-factor authentication service APIs can be used to Create a MFA app and users, Associate a mobile user, Validate the user and thereafter authenticated those registered users against your applications. Tokens generated for authenticating users can be delivery via SMS, Voice (Text to Speech) or via Push notification delivery service.
To invoke the SMFA service using SMS token Delivery, Customers will need a Sender ID (Shortcode) or if recipients are in US, may use a default Public channel provided by Syniverse.
To execute a MFA call, Customers will need to have the following information ready:
SMFA Base URL: https://api.syniverse.com/scg-external-api/api/v1
A Channel ID or a Sender ID. SCG provides a Public Channel ID for your convenience. Please note that if you are Authenticating user outside of the US, a Private Sender ID (Longcode/shortcode) is required.
Bearer Token: This is your Access token that is generated with your registered application.
Using your application, below are the sequence of events to perform a MFA:
1. Create MFA application with public channel or Sender ID
The MFA application should include the following:
"name" = name of your application
"description" = description of your MFA application service
"auth_code_length" = Number of characters you want your code to be.
"auth_token_type" = token type which could be (NUMERIC, COMPLEX, ALPHA, ALPHANUMERIC)
"auth_token_validity_duration" = validity period of your token (in secs)
"message_from" = This is the sender ID (Shortcode, Longcode, PUSH ) you have provisioned for your MFA application to deliver token to the end-user's address
"associate_template" = Body message you want to use to compose the token delivery instructions to the user. Includes inline template attributes ${display_name} and ${PIN}
"login_template" = Body message to subsequently use in composing a delivery token message to the user
curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d {"name":"Kolanator_MFA Service","description":"Kolanator website mfa service","auth_code_length":6, "auth_token_type":"NUMERIC","auth_token_validity_duration":"600","message_from":"NdET2v9bQGVws4DOJyM758","associate_template":"Please verify your mobile number by entering the ${display_name} validation code ${pin}. Reply STOP to end ", "login_template":"Your ${display_name} validation code is ${pin}. Enter the code in the next ${validity_duration} min. Reply STOP to end ' https://api.syniverse.com/mfa/v1/applications
Response: {XkpeXN1wkJK4ay0wKcwvC1}
2. Associate a user with your application
This associates a user’s mobile number with the application that was created. You need to use the identifier that was created when the application was created.
You will need the following values:
Application ID - from when the MFA was created (XkpeXN1wkJK4ay0wKcwvC1)
User ID - A unique identifier that you can create for the user you are trying to associate with your application. This could be the name of the user, or an account number, e.g David_Smith
curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{"display_name":"Kolanator", "address":"+14085551212"}' https://api.syniverse.com/mfa/v1/applications/XkpeXN1wkJK4ay0wKcwvC1/users/David_Smith/associate
3. Validate a user
This validates that the user’s mobile number is authenticated with your application.
curl -X POST \
https://api.syniverse.com/mfa/v1/applications/XkpeXN1wkJK4ay0wKcwvC1/users/David_Smith/validate \
-H 'Authorization: Bearer Token' \
-H 'Content-Type: application/json' \
-d '{"validation_code":"839020"}'
4. Login start
This is the subsequent call made to authenticated the user anytime they log in to your application. This call is optional and solely dependent on your authentication policy
curl -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{"display_name":"Kolanator"}' https://api.syniverse.com/mfa/v1/applications/XkpeXM1wkJK4ay0wKcwvC1/users/David_Smith/login_start
For more information on how to use the resources, please check out the API resource document on the SDC portal
View ArticleDownload Transaction reports via SCG Message Console
Log in to SCG Message Console
On the left side Navigation bar, Click on Reports
Select Report type (Messages for SMS, MMS transaction, Calls for Voice related transactions)
In the Report menu, in the Channel type field, select the appropriate Channel, you want to view/download a report for e.g. SMS or MMS. Note that you can leave blank and this will pull transactions for all Channel types
Next, select a Date Range and click the View Report Button
You should be able to View the transactions for the Date range specified
To export the Generated report in a .csv format, click on thebutton to begin the processing of the data for download. You can check the status of the process by clicking the “Last Export Status” button
Once the process as been completed, click “Download your Export” to download your report.
View ArticleTo receive messages/events from SCG to your application, you can setup a delivery configuration (webhook) and Subscribe to the SCG-Message topic to have these events posted to their application as JSON/XML object.
Example of events in the SCG-Message that can be posted to the customer's application include:
DR (Message Delivery Receipts)
MO (Mobile Originated Messages)
Sender ID events
Contact status events
Delivery Configuration (webhook) setup :
Select Events Manager from the SDC portal and click on Delivery Configuration
Click on New Delivery Configuration
Complete the configuration setup by adding your configuration name, callback url (Address) and click Createto complete the delivery configuration setup
Subscribe to SCG-Message Topic
Navigate to Events Manager and select Subscriptions
Click on New Subscription
Complete the Subscription form by selecting "SCG-Message" from the Topic field
In the Event Type, the default is "all types" but you can select specific events in the Event Type field.
Select your Delivery configuration from the drop down
Select a startdate and an end date if so desired. End dates/time are not mandatory
Select Createto complete the subscription setup
Once completed, you should see a subscription with your delivery configuration like below:
Sample Event:
MT ( Mobile Termination) Event:
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"attachment_ids": "UIRqnwwhbLS106HNECVzG5",
"previous_state": "SENT",
"message_request_id": "96Wf3kBe2DJXhyqBOxsFO6",
"message_id": "176ySDuGoChplVgiz2lcm7",
"to_address": "+14085551212",
"has_attachment": true,
"reason_description": "SUCCESS",
"application_id": 1764,
"reason_code": "200",
"sender_id_alias": "Gladiator",
"company-id": 1512,
"sender_id_id": "RexWQXiD7pF7KzvepiygC7",
"external_message_request_id": "",
"new_state": "DELIVERED",
"fragments_count": 1,
"from_address": "662453",
"mt_price": 0.035
},
"evt-tp": "message_state_change",
"timestamp": "2019-09-21T01:00:38.89Z"
},
"event-id": "p0UFoavETOWmOf3zBCRYLw"
}
(MO) Mobile Origination event
{
"topic":"SCG-Message",
"attempt":1,
"event":{
"fld-val-list":{
"sender_id_alias":"xxxxxxxxxxxxxxxxxxxxxxx",
"mo_price":0.005,
"company-id":xxx,
"sender_id_id":"xxxxxxxxxxxxxxxxxxxxxxxxxx",
"message_body":"Test MO message",
"message_id":"6QX2csWrr064RzxhwHo0m7",
"to_address":"662453",
"has_attachment":false,
"fragments_count":1,
"from_address":"+14085551212",
"application_id":304
},
"evt-tp":"mo_message_received",
"timestamp":"2017-11-30T17:17:46.615Z"
},
"event-id":"jX5nAV9USriK2LkS6e0D0g"
View ArticleOne of the features marketers and developers can expect to see on the Syniverse Communication Gateway is the ability to create and use templates to compose SMS messages used to interact with end-users.
Templates provides the ease of composing messages especially if the business wants to send the same message content to multiple users.
Public Templates
SCG provides sample templates that customers can use out of the box. We call this Public templates. This are pre-defined templates for specific but commonly seen use cases for engaging end-user via SMS.
Below are a list of public templates available on the platform:
Public shipping alerts
Public SMFA- Requires Sniverse Multi-factor Authentication service
Public Password reset
Public Appointment notification
Public Flight alerts
Public Delivery alerts
Public Pickup alerts
Private Templates
Users can also create their own templates and customize it for use with their message deliver. Users can create a template via the UI console or via API.
Via UI Console
Navigate to the Template menu on the left nav bar in the Messaging console and select "Template"
Click onto create new template using the $ and curly brackets to designate your variables e.g ${name}
Click save to same your template
Via API
Create Template
curl -X POST -H "Authorization: Bearer Token" -H "Content-Type: application/json" -d '{"designation":"TEMPLATE","name":"Kolanator_Alerts","pattern":"Dear ${Customer_name}, this is to inform you that your order ${Order_number} has shipped. Thank you"}'
https://api.syniverse.com/scg-external-api/api/v1/messaging/message_templates
Send a Message using a Template
Users can send a message with a template once its been created or they can use a public template if so desired.
Send a message using a template via the Message Console
In the Send Message menu, populate the "From" and "To" fields as desired
Select your desired template by clicking the drop down button in the "Template" field
Complete the information in the Template variables fields of your template
View the "Message Result" to verify your message
Click "Send" to submit the message for delivery.
Send a message using a template via the API
curl -X POST -H "Authorization: Bearer Token" -H "Content-Type: application/json" -d '{"from":"OfX4r7DeQrh7HXXHyqb5m5","to":"+14085551212","body":"#set($customer_name=\"Kolanator\")\n#set($Ref_Number=\"12344TP\")\n#set($link=\"http://www.kolanator.com\")\n#parse(\"Shipping_Alert\")"}' https://api.syniverse.com/scg-external-api/api/v1/messaging/messages
View ArticleShortcodes are unique identifiers that are required to send application-to Person (A2P) messages to end-users. There are 2 main types of shortcodes in most countries.
Vanity shortcodes
Numeric (Non-Vanity shortcodes)
Obtaining a Vanity Short Code: Not only are there dedicated short codes, there are also vanity, and non-vanity short codes. Vanity short codes are 5-6 digits, and are specifically selected. Usually vanity short codes are selected over non-vanity short codes, because they’re easier for consumers to remember the numbers. For example, vanity short codes would be numbers like 12345, 313131, 99000, etc.
Non-vanity short codes are 5-6 digits, and are selected at random by the Common Shortcode Administrator (CSCA). For example, non-vanity short codes would be numbers like 49732, 958372, 34930, etc. It’s interesting to note that the majority of SMS short codes are non-vanity short codes.
What are the rules governing Short Codes?
CTIA Rules: To protect consumers against bad apples, the wireless carriers set up a group called the CTIA to enforce SMS marketing practices that are in the best interests of the consumer. To do this, the CTIA carries out audits on SMS programs based on the rules found in their CTIA Short Code Compliance Handbook.If a text messaging campaign is found to be in violation of any of the guidelines in the CTIA Short Code Compliance Handbook, the text messaging campaign can be deactivated by the wireless carriers.
TCPA Rules: Before starting an SMS marketing campaign, it’s important to understand what the Telephone Consumer Protection Act (TCPA) is, and what you as a business needs to do to remain compliant with the TCPA while running a text message marketing campaign on a short code. A link to the rules can be found here
North America SMS Messaging:
Short Code Messaging: An SMS short code can send both text messages (plain text 160 characters), commonly referred to as SMS and multimedia messages (images, videos, long plain text), and commonly referred to as MMS. An SMS short code must be provisioned specially with the wireless carriers to send and receive MMS messages.
How much does it cost to lease a Short Code? When a dedicated SMS short code is approved, a business must then pay for the dedicated short code lease, before they can start the wireless carrier approval process. Customers can lease their shortcode directly from CSCA or through the Syniverse Developer community portal. A monthly lease on a dedicated SMS short code will cost a business $1,000. Businesses can pay for their dedicated sms short code leases by credit card, electronic funds transfer, and check. It’s important to note that in addition to the lease of the dedicated SMS short code, a business may also have to pay to setup the short code, in addition to hosting the short code.
Wireless Carrier Approval Process: When the Common Short Code Administration approves your short code application, then it’s time to get each and every wireless carrier to approve your SMS campaign. This process usually requires much more information about your SMS campaign than is required for the Common Short Code Administration application.
View ArticleWhat you need to know about WhatsApp Business User Engagement
Businesses may only contact people on WhatsApp if: (a) they have given you their mobile phone number; and (b) they have agreed to be contacted by you over WhatsApp. You are solely responsible for providing appropriate notices and disclosures to, and obtaining appropriate consents from, people.
In order to send a WhatsApp message to a person, you must receive opt-in permission in-line and contextually during the relevant user flows. For example, to receive a receipt via WhatsApp, a person must opt in during a purchase flow. Opt-in obtained without context and in any manner not related to an action the user is already taking, does not comply with this policy.
Opt-in permissions must display a visual element (e.g. a check box) next to the WhatsApp name and logo, with adjacent language clearly stating: (a) what type of information you will send to your customer; and (b) that you will message it via WhatsApp. You must give the person control over which WhatsApp number is used for the opt in, such as by giving the person the ability to edit the phone number.
Businesses must respect all requests (either on or off WhatsApp) by a person to block, discontinue, or otherwise opt out of communications from you via WhatsApp, including removing that person from your contacts list.
Businesses may only contact children on WhatsApp in compliance with applicable law.
Acceptable Message Types
If a person initiates a chat with you, you may continue that conversation via the WhatsApp Channel for up to 24 hours after the last message sent to you by that person (“Customer Service Window”). Outside of the Customer Service Window, you may only send messages via approved Message Templates, for which we will charge the applicable rate.
Any Message Templates must comply with WhatsApp’s terms and these policies. WhatsApp will review and approve all Message Templates.
You may only send transactional notifications and initiate chats via approved Message Templates (as defined in our API Documentation), subject to applicable pricing.
You may not send newsletters.
You may not send advertising, marketing, or promotional messages.
You may not build games or support playing of games in WhatsApp, including any interactive program for one or more players that involves skill, competition, and/or chance.
WhatsApp Business Commercial rules
The WhatsApp Business Channel messaging supports Templated Messages. Businesses are required to submit and get approval from WhatsApp for all Templates. Only when a Template is approved can it be used to engage users.
All Templated messages are billable per our listed pricing for each applicable country.
Syniverse determines the price of each delivered Templated message based upon the country code of the recipient. For example, a +44 country code phone number is charged at the United Kingdom price.
Syniverse will charge you for each Templated Message that is sent.
Conversational Messaging is also supported and Syniverse will charge a monthly fee for a fixed number of Conversational messages. Conversational messaging is triggered if a user initiates messaging with the Business and covers any message received and sent between the user and the Business for up to 24 hours ("Conversational Chat Window"). Any additional message the Business sends to that customer beyond the 24 hr Window must be a Templated Message, for which we will charge you as set forth in our Template Message pricing
We have the right to update list prices and pricing rules on a monthly basis, and changes will take effect the first day of the calendar month following such changes.
Exclusions. The WhatsApp Business Solution may not be used to send any messages to or from the following countries and regions: Crimea, Cuba, Iran, North Korea, and Syria
Any Message Templates must comply with WhatsApp terms and policies. WhatsApp has the right to review and approve any Message Templates.
You may only send transactional notifications and initiate chats via approved Message Templates and its subject to applicable pricing
You may not send newsletters.
You may not send advertising, marketing, or promotional messages.
You may not build games or support playing of games in WhatsApp, including any interactive program for one or more players that involves skill, competition, and/or chance
View ArticleCustomers that already have their own Longcode numbers or Toll-free numbers can migrate them to the Syniverse Communication Gateway to be used for sending messages. Customers most ensure that all the necessary approvals from the TN Sponsor including purchase receipts and SPIDs associated with these numbers are available.
Syniverse Cloud messaging services offers 2 options to customers with US or Canadian SMS-enabled Telephone Numbers (TN) to use them as Sender IDs for their P2P messaging applications:
Customers with TNs (Owns a SPID -Service Provider ID) and a Carrier-approved or grandfathered P2P use case.
Batch Import Via API
Submit your SPID to Syniverse for registration. (Please note that this requires a syniverse Implementation Manager to work with you on gathering all necessary information required to complete registration)
Once SPID/NNID registration is completed, submit a Batch Import for Sender ID Via API
Create import job for SenderIds - Format : csv file
Upload the attachment for numbers (csv template for numbers import will be provided to you by the Syniverse Implementation team)
curl 'https://api.syniverse.com/scg-external-api/api/v1/messaging/attachments' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json;charset=UTF-8' --data-binary '{"designation":"SENDERIDS_IMPORT", "name":"Longcode Import","type":"application/vnd.ms-excel","filename":"LongcodeImportTemplate.csv"}'
Response will return the attachmentId - { tI5FuL12SivTANIv1BOXeMN}
Create the Access Token for Uploading Attachment Data (Returns Access Token)
curl 'https://api.syniverse.com/scg-external-api/api/v1/access_tokens' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json;charset=UTF-8' --data-binary '{"resource":"ATTACHMENT","resource_id":"tI5FuL12SivTANIv1BOXMN"}'
{PfytmJmH56J5hz3J6J1hU}
Upload Attachment Data (using the access token)
curl 'https://api.syniverse.com/scg-attachment/api/v1/messaging/attachments/<use the accesstoken returned from the above step>/content' -X POST --data-binary @"/cygdrive/c/numbers/LongcodeImportTemplate.csv" -H "Content-Type: application/octet-stream"
Repeat Steps above to upload receipts
Create Sender Id Import Job (TN file) using attachment ID
curl -v -X POST -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{"import_attachment_id":" tI5FuL12SivTANIv1BOXeMN ", "receipts_attachment_id":"JibQ84mqM5gDjjisbnvPB2","register_number":false}' https://api.syniverse.com/scg-external-api/api/v1/sender_ids_import
Optional
Check import job - state can be CREATED, RUNNING, COMPLETED. When COMPLETED, imported_count is the count of numbers imported and created as #private SenderId, Please take in mind that phone number should be unique, but also the name of number (SenderId name respectively)
curl -X GET -H "Authorization: Bearer TOKEN" -H "ContentType: application/json" https://api.syniverse.com/scg-external-api/api/v1/sender_ids_import/i4SJ1E5Q2oIiXNEI1LA1X1
Batch Import via SCG UI
Submit your SPID to Syniverse for registration.
Log in to the SCG UI
Navigate to “Messaging Accounts” menu
Select “Sender Address” and click on “+Purchase or Migrate Sender Address” Button
In the Purchase or Migrate Sender Address window, make sure the right Country is selected and Longcode button is selected, then click on the link to migrate your number
Navigate to the “Download CSV template” link and download the csv template for Sender IDs
Fill in your TNs following the format outlined
Upload the file using the “Select File” button.
Once completed, click the upload button
Now navigate to the upload receipt field and click the “Select File” button to upload your receipt or LOA. Note that you can also email your LOA to your Sales rep if applicable.
Complete the rest of the Sender ID form making sure not to check the “Register Number*. Submit the form and Sender IDs will be automatically generated for your TNs
Customers with TNs/TFN (Migration to Syniverse SPID/Use Case)
This option provides customers with the use of Syniverse’s SPID and approved use case for P2P SMS messaging. Customers are required to have a signed (LOA- Letter of Authorization) from their TN sponsor and a receipt showing ownership of the TNs.
For Toll-free numbers TFN used for A2P use cases, SPID/NNID is not required. Customer are however required to have a valid and acceptable use case and follow all TCPA rules with regards to consent and message content.
Via API : Follow same steps as above. Ensure that the “register_number” is “true”
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name":"Kolanator Toll-free Campaign2","class_id":"COMMERCIAL","type_id":"TOLLFREE","address":"18004445555","country":"USA","consent_managed_by":"USER","register_number":"true","capabilities":["SMS"],"billing":{"receipt": " Kola Receipt","expiration_date":"12.13.2028","company_name":"Kolanator","authorized_user":"Kola","phone":"+14086881111","email":"[email protected]","message_type":"SMS","description":" Messaging SC Production campaign ","shortcode_type":"NUMERIC","campaign_type":"TRANSACTIONAL","campaign_website":"www.kolanator.com","campaign_discovery":"Website", "country":"USA","expected_date_of_service": "","use_case": "Alerts","estimated_volume":"1000000"}}'
If Longcode, set "type_id" = LONGCODE.
Via SCG UI : Follow same steps as above. Ensure that the “register numbers” button is checked.
*Please note that registration with Netnumber is required and validation of documents submitted is required before Sender IDs are created for customers TNs.
Toll-Free Numbers can be text-enabled via this process, however additional provisioning is required on the Syniverse platform to complete activation.
View Article25MB
View ArticleUsing the API, you can send upto 2000 characters. 320 Characters limit using the SCG UI.
View ArticleCustomers can programmatically receive MO messages with attachments sent to their application. These MO messages with attachment could be of the following Channels:
MMS
Facebook Messenger
WhatsApp Business Messaging
WeChat
RCS
Receiving MO messages with Attachment
Assuming you already have a MMS capable Sender ID in the case of a Shortcode or Longcode or have a Facebook, WhatsApp or RCS capable sender ID provisioned.
When an end-user sends you a MO message with an image or video to your shortcode, long code or any other media capable Sender Address, the message will be deposited directly into your Inbox. For you to receive this in your application, you will be required to setup a webhook and have subscription configured for receiving messages. This will enable you to get MO events. For more information on setting up a webhook, please visit our webhook knowledgebase
MO Events with Attachments
MO message events are POSTED to your webhook once you have the event and delivery configuration setup. Below is a sample of an event you will get for a MO MMS with an attachment
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {"attachment_ids": " Mno4Xayql1oVOYAvP7Iy25",
"sender_id_alias": "ljX2KJbs8zowzC8rFexzn6",
"mo_price": 0.015,
"company-id": 1512,
"sender_id_id": "ljX2KJbs8zowzC8rFexzn6",
"message_body": "",
"message_id": "WGqCwdXm2szqkIGq2Xmy06",
"to_address": "18322222222",
"has_attachment": true,
"fragments_count": 1,
"from_address": "+14086080000",
"application_id": 1714
},
"evt-tp": "mo_message_received",
"timestamp": "2019-07-16T16:16:17.579Z"
},
"event-id": "mNdHyWhdQWW2wACUWh84Wg"
}
Retrieving MO Message content using the Attachment ID
To confirm that you have an event with a media content sent to you by a user, the event (JSON) sent to you will include having the following parameter and values:
{has_attachment}: {True}
{attachment}: {attachment ID}
Now that you have an attachment ID, complete the following sequence:
Step 1 : Create an Access Token for the attachment
curl -X POST
https://api.syniverse.com/scg-external-api/api/v1/access_tokens
-H Authorization: Bearer {TOKEN}
-H Content-Type: application/json
-d {"resource": "ATTACHMENT","resource_id": " WGqCwdXm2szqkIGq2Xmy06”}
The value for the resource ID parameter should be the same as the attachment ID you got in your event
Response: {“ ARuMnnEtpiqEUrlxvbOeS4”}
Step 2: Get/Download your Attachment
Using the ID received from creating the access token: {“ ARuMnnEtpiqEUrlxvbOeS4”}, run a GET on with the ID embedded in the resource below. Ensure that you have the correct heards configured if you want to download the content.
curl -X GET \
https://api.syniverse.com/scg-attachment/api/v1/messaging/attachments/ARuMnnEtpiqEUrlxvbOeS4/content
-H Authorization: Bearer {TOKEN}
-H Content-Type: image/jpg
Your content should be downloaded now!
Please note that each channel may have different requirement in the type of content type that is supported. For MMS related content, please visit the Syniverse knowledge base portal for content type supported.
For information on the API resources used in here, please visit our API reference page.
View ArticleA Private channel makes it easier to use your sender address.
Once you have purchased your sender address you should select private channels and then 'add private channel'
You can then select the Sender Address(es) to use with the channel.
View ArticleOverview
Syniverse Consent Management is a managed solution available with your SCG (Syniverse Communication Gateway) SMS service. This solution provides businesses the flexibility to have Syniverse add a managed consent layer to their service that primarily manages the consent status, tracking, and auditing to ensure compliance with local laws and regulations. This solution is currently only available on US issued Shortcodes with approved SMS/MMS campaigns.
Below is a user guide on how managed consent works and how to use it. Please note that a subscription to the Consent Management service is required along with a fully provisioned Shortcode.
Capturing Consent (End-user Opt-in)
There are 2 main methods of capturing use consent for Messaging campaigns:
Single Opt-in consent: This is usually when a user responds to a request to receive SMS or MMS messages on their mobile number from a business. The most common single opt-in use case is a user responding to a request by sending a MO (Mobile originated) message from their mobile number with a specific “Keyword” in the body of a message to a Customer’s shortcode.
For example:
End-user sends Keyword= START to Customer’s Shortcode 55555from the user’s mobile number.
Syniverse’s check to see if the Shortcode is provisioned as Syniverse managed and if so processes the consent request by marking the user as Opt-in (consent_status =OPTIN) and associates this with Customer’s Shortcode
Syniverse also sends the Customer a MO event with the message body = "Keyword" to their application via a webhook if present.
A customizable welcome message is sent to the end-user e.g
{"Welcome to Syniverse Communication gateway! Msg&data may apply. Reply HELP for help, Reply STOP to cancel"}
This Opt-in method is known as Single Opt-in as a confirmation of the intent to consent to receiving messages from the Customer is not required.
SDC portal
Double Opt-in Consent: This type of consent is usually required when a business is capturing the consent of a user to receive SMS or MMS messages from the Business. This involves an initial capture of a user’s mobile number either via a Web application, a POS interaction or via a mobile application. The Business then initiates a secondary Opt-in by sending a confirmation message to the captured Mobile number to validate and confirm that the user intends to give the required consent.
For example:
Customer sends a consent request <Solicit Consent> to Syniverse via API with end-user’s Mobile number
Syniverse processes the request and sends a confirmation message via SMS to the supplied Mobile number.
End-user replies with a Yes or NO to the confirmation message
If End-user replies with a Yes, Syniverse sends a Welcome CTA message (customizable by Customer) to the end-user
Syniverse also send a MO event with a Message body = Yes to the Customer’s webhook
Syniverse processes and stores the consent record (consent_status = OPTIN) with the end-user’s mobile number associated with the Customer’s shortcode
This Opt-in method is known as Double Opt-in as a confirmation of the intent to consent to receiving messages from the Customer is required.
Using the Syniverse Consent Management service
The Syniverse consent management service is integrated with your SMS service. You can make REST calls via the API to perform the following functions:
Please note that prior to invoking any of these commands below, you must have signed up for the Syniverse consent management service and have it provisioned with a valid Shortcode and a valid Carrier approved Messaging Campaign. Other key information you need to have includes:
Campaign Keywords (If single Opt-in) e.g. START, JOIN, MOVIES etc.
Welcome Message (Optional), If none is provided, Syniverse will use default
Opt-out message (Optional), if none is provided, Syniverse will use default.
Please note that the above key info need to be provided to Syniverse prior to activating consent management service
Send <Solicit Consent>: This command lets you submit a request to seek an End-user’s consent if you acquired their mobile number via a channel that is not SMS for instance Web, App, POS, walk-ins. The request will trigger a confirmation MT to complete a double Opt-in consent flow.
**Note that Customersdon'thave to trigger SMS MO opt-ins. This is usually triggered when an end-user sends a MO SMS message to your configured Opt-in keyword
Sample Request:
curl -X POST -H "Authorization: Bearer d17f79e76e30d7a0f05e6456b0bbc78a" -H "Content-Type: application/json" -d '{"address_type":"LONGCODE","address":"+14085551212","sender_id":"i7GQ7hxAmiDsIArveY3qm3"}' https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
where:
Base URI: https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
Bearer Token: Authentication Key from your Syniverse application on your messaging subscription
address_type: Longcode (This is always a Longcode)
address: This is the end-user’s mobile number
Sender ID: This is the unique ID generated for your Sender address (Shortcode)
<List Consent status>: This command lets you list the status of all the end-user’s mobile number associated with your shortcode in the Consent Management database. Please note that if you have other Programs in your account with Mobile numbers that are not associated with a Syniverse managed sender address (shortcode), those numbers will be listed too, but they will have a different value in the “consent status” field. See sample below
Sample Request
curl -X GET -H "Authorization: Bearer d17f79e76e30d7a0f05e6555b0bbc78a" https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
where:
Base URI: https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
Bearer Token: Authentication Key from your Syniverse application on your messaging subscription
Sample Result
{
"application_id": 2305,
"company_id": 1512,
"created_date": 1553809333006,
"last_updated_date": 1554416172279,
"version_number": 2,
"id": "h05iW1neHgo19pYMmAQ6s4",
"address_type": "LONGCODE",
"address": "+14085551212",
"sender_id": "qvPzyySQq4LBgvzbgpnNH1",
"consent_status": "OPTOUT",
"from_address": "55555",
"opt_in_type": "SMS",
"opt_out_type": "SMS"
}
Consent Status values:
OPTIN: Messages will be sent to end-user with this value
OPTOUT: Messages will not be sent to end-users with this value
NONE: Messages will be sent to end-user as this is assumed to have a Consent managed by the customer
<Delete Consent Record>: This command lets the user delete a consent record of the mobile number from the database. You should be very careful using this command and it is recommended that you only invoke this command if an end-user has revoked their consent by either sending a request to you, changes carriers or send an Opt-out request via a MO message using any of the Opt-out keywords below in the Opt-out/Consent revoke section.
Please note that US regulations under TCPA also mandates other forms of opt-out including via email, verbally or in-person.
Sample Request
curl -X DELETE -H "Authorization: Bearer d17f79e76e30d7a0f05e65589b0bbc78a" https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses /Q6xviejOT23ew0X5Yf6Fp4
where:
Base URI: https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
Bearer Token: Authentication Key from your Syniverse application on your messaging subscription
Id: Q6xviejOT23ew0X5Yf6Fp4 (A unique consent status ID associated with a particular mobile number)
Customer should perform a GET to List the consent status result of which will give them the consent status ID they will need to delete a record from the database
OPT-OUT/Consent Revoke
The Syniverse Managed Consent support the revoking of consent by users or as mandated by the messaging campaign approved by the US carriers.
End-users can revoke a consent by Opting out of a Program associated with a shortcode. The most common form of Opt-out is by the end-user sending a STOP keyword to a Shortcode. There are other keywords that are supported as Opt-out Keywords:
End
Cancel
Unsubscribe
Quit
STOP ALL
The Syniverse Managed consent automatically processes SMS MO Opt-out keywords and notify the Customer via MO callback event.
End-users can also request to Opt-out of a program by contacting the Customer via email, POS or by telephone. Customers are obligated to process this request by invoking an Opt-out process.
Opt-out /Consent Revoke by Customer Notification
<Contact Opt-out via API> : Customers can invoke the contact Opt-out API to revoke consent for a subscriber that is in the consent management database. This use case is typically performed when a subscriber contacts the Customer via POS, website, email or any other approved channel besides sending a SMS MO opt-out keyword.
Sample Request: Customer Triggered Opt-Out
curl -X POST -H "Authorization: Bearer d17f79e76e30d7a0f05e6558922bbc78a " -H "Content-Type: application/json" -d '{"sender_id":"51RLyL2S2wZGBuTrXri4E1","addresses":["+14085551212","+18135551212"]}' https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses/optout
where:
Base URI: https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses/optout
Bearer Token: Authentication Key from your Syniverse application on your messaging subscription
Sender Id: 51RLyL2S2wZGBuTrXri4E1 (This is the Sender ID for your shortcode number)
Addresses: End-user’s mobile phone numbers that you wish to opt-out of the consent database
A consent status event will be “Posted” back to the customer via the Sender ID event topic.
For all other Opt-out methods, Customer needs to invoke the “Delete Consent Record” API to remove the user’s record from the consent database. Customer should perform a GET to “List” the consent statuses of end-users in their program, result of which will give them the consent status ID associated with a particular phone number they will need to delete a record from the database
All subsequent messages to a Mobile number associated with your Shortcode that has a consent status value of Opt-out will be rejected with a failure response “No Consent”
Subscriber Consent Discovery Channel attribute
The Subscriber Consent Discovery Channel attribute allows customers to specify which channel a particular end-user opts in/gave initial consent from (discovers your program) . The discovery channel attributes are:
Opt_in_type
Opt_out_type
Opt-in/Opt-out type value can be of:
web
IVR
app
email
POS
Other (Default if no value is given)
SMS (Value for all MO Keyword Opt-in/Opt-out)
For all the new Opt-in/opt-out type values, the information will come from the customer in all cases except for SMS opt-in and opt-out which comes directly to SCG.
SCG will process and store the values for the new attributes against the end-user records in the consent management database. Relevant events associated with the successful API call to opt-in or opt-out a particular end-user will be included in the events posted back to the customer’s application via their configured webhook.
These new attributes will be available in both the Syniverse Managed Consent service and the SCG Unsolicited Opt-out service.
Sample Solicit Consent (Opt-in) resource with Opt-in type attribute
Using the attribute "opt_in_type” in the Solicit Consent API resource
curl -X POST -H "Authorization: Bearer 8f8a41a5799eff1661a54e920d16f95"
-H "Content-Type: application/json" -d '{"address_type":"LONGCODE","address":"+14085551212", "opt_in_type":"web",
"sender_id":"i7GQ7hxAxNDsIArveY5qm3"} https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
API Endpoint: https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
address_type: The type of end-user address being opted in. e.g. Longcode (Regular E164 mobile number),
sender _id: The unique ID for the customers shortcode
address: The mobile number that the customer is requesting opt-in consent for (E.164)
opt_in_type: The discovery channel from which the end-user gave initial consent. See available values above.
Sample End-user Opt-out resource with new Opt-out Type attribute
Using the attribute “opt_out_type” in the End-user Opt-out resource
curl -X POST -H "Authorization: Bearer 8f8a41a5996eff1641a66e920d16f95" -H "Content-Type: application/json" -d '
{“sender_id”:“51RLyL2S2wYGBuTrXri4E1”,“addresses”:[“+14085551212”],“opt_out_type”:“email”}' https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses/optout
API Endpoint: https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
address_type: The type of end-user address being opted in. e.g. Longcode (Regular E164 mobile number),
sender _id: The unique ID for the customers shortcode
address: The mobile number that the customer is requesting opt-in consent for (E.164)
opt_out_type: The discovery channel from which the end-user gave initial consent. See available values above.
Other resources in the GET, UPDATE and LIST API's
List consent status
curl -X GET -H "Authorization: Bearer 2d36a89c-cd98-337a-8d50-491e65f2dbb8" https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
List Consent for a particular consentId
curl -X GET -H "Authorization: Bearer 2d36a89c-cd98-337a-8d50-491e65f2dbb8" https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses/OgC142KNOldkS0o6pj3MV6
Sender ID Consent Event Status
To get consent status for end-users on a particular shortcode, Customers can setup a webhook (Delivery configuration) and subscribe to the SCG-Sender-ID topic.
The SCG-Sender-ID topic has the event “sender_id_recipient_consent_change”. This event contains the change in consent status of a particular recipient.
How to setup and subscribe to the SCG-Sender-ID topic
Delivery Configuration (webhook) setup:
Select Events Manager from the and click on Delivery Configuration
Click on New Delivery Configuration
Complete the configuration setup by adding your configuration name, callback URL (Address) and click Create to complete the delivery configuration setup
Subscribe to SCG-Sender-ID Topic
Navigate to Events Manager and select Subscriptions
Click on New Subscription
Complete the Subscription form by selecting "SCG-Sender" from the Topic field
In the Event Type, the default is "all types" but you can select specific events in the Event Type field.
Select your Delivery configuration from the drop down
Select a start date and an end date if so desired. End dates/time are not mandatory
Select Create to complete subscription setup
Sample
{"topic":"SCG-Sender-ID","attempt":1,"event":{"fld-val-list":{"company-id":9002,"sender_id_id":"yKTJEeK90YX01O69ighea1","consent_status":"OPTIN","recipient_address":"+14085551212","application_id":106},"evt-tp":"sender_id_recipient_consent_change","timestamp":"2018-02-23T20:36:04.97Z"},"event-id":"eImNljiSQUyz4b0gFZkfKg"}
{"topic":"SCG-Sender-ID","attempt":1,"event":{"fld-val-list":{"company-id":9002,"sender_id_id":"yKTJEeK90YX01O69ihsea1","consent_status":"OPTOUT","recipient_address":"+14085551212","application_id":106},"evt-tp":"sender_id_recipient_consent_change","timestamp":"2018-02-23T20:38:41.004Z"},"event-id":"tMS4eJK9Q7O6o6npRTRXXw"}
The event “sender_id_recipient_consent_change”contains the change in consent status of a particular recipient/end-user
Sample consent status events
{"topic":"SCG-Sender-ID","attempt":1,"event":{"fld-val-list":{"company-id":9002,"sender_id_id":"yKTJEeK90YX89O69ighea1","consent_status":"OPTIN", “opt_in_type”:“web”, "recipient_address":"+14085551212","application_id":106},"evt-tp":"sender_id_recipient_consent_change","timestamp":"2018-02-23T20:36:04.97Z"},"event-id":"eImNljiSQUyz4b0gFZkfKg"}
{"topic":"SCG-Sender-ID","attempt":1,"event":{"fld-val-list":{"company-id":9002,"sender_id_id":"yKTJEeK90YX89O69ihsea1","consent_status":"OPTOUT",“opt_out_type”:“ SMS”,"recipient_address":"+14085551212","application_id":106},"evt-tp":"sender_id_recipient_consent_change","timestamp":"2018-02-23T20:38:41.004Z"},"event-id":"tMS4eJK9Q7O6o6npRTRXXw"}
View ArticleSyniverse Chatbot Connector Service (Developer Preview)
The service allows Syniverse Cloud messaging customer to leverage SCG (Syniverse Communication Gateway) message delivery channels and provide connectivity to external entities which expose messaging APIs and for which this service has a corresponding API module (or plugin) in place.
Syniverse Connector Service
The Syniverse Connector service provides Customers Chatbot Service accounts hosted on Cloud platforms a dedicated connector that allows them to create and enable a Syniverse messaging channel for their Bot services to communicate with their end-users.
The service will provide REST endpoint “connectors” where the user will be able to do CRUD operations for its connectors. The connector entity will contain configuration information needed for the corresponding service instance to function, like:
A dedicated Syniverse Sender ID ( https://sdcdocumentation.syniverse.com/index.php/sms-mms/user-guides/sms-mms-user-guide )
API type e.g. (Direct Line API) or Google DialogFlow
Configuration information about this API, like URLs (if not well known), credentials
State - ACTIVE/INACTIVE
As soon as a connector is put by the user in state ACTIVE it will begin to function.
SCG_CONNECT_DEFAULT_CONVERSATION_IDLE_TIMEOUT (2 * 60)
After this time with no MO the conversation will be considered finished and will be closed. Subsequent message from the same user will open a new conversation.
Connector Service Integration
Connector service is now available for the following services:
MS Azure Cloud Connector
Using the MS Azure Bot Direct Line API to Syniverse Messaging services. The connector service is able to translate session-oriented APIs like the Direct Link into paging-oriented APIs like SMS, MMS by emulating session behavior based on a Syniverse Sender ID, end-user contact (MDN) and time. The service can also be used with other Syniverse Messaging Channels that are IP-based.
Google DialogFlow Connector
Google DialogFlow connectors can be used with the Syniverse Messaging channels. The Syniverse Connector service allows customers using DialogFlow to create their Chatbot to enable a Syniverse Channel to communicate with their end-users via any number of available channels. A Dialogflow account and Google Cloud platform credentials are required to use this connector. MTs are received as response to the request that sends the MO. Conversations are created implicitly.
Syniverse Messaging Channels for Connectors
The Syniverse Messaging channels that can be leveraged on the Syniverse connector service include:
SMS
Facebook Messenger
RCS
WhatsApp
Prerequisite to using the Syniverse Connector service
Syniverse Cloud Messaging Account with a subscription to Voice and Messaging service ( https://developer.syniverse.com )
A valid Dedicated Sender ID (Can be a Shortcode, Longcode, or toll-free number. Can also be a Sender ID configured for RCS, WhatsApp or Facebook Messenger).
For Microsoft (MS) Azure Chatbots
A configured Bot on the MS Azure Cloud portal ( https://docs.microsoft.com/en-us/azure/bot-service/bot-service-quickstart?view=azure-bot-service-4.0 )
Subscription to Direct Line Channel on the MS Azure portal
Your Azure Channel Secret Key
For Google DialogFlow Chatbots
A configured Chatbot on the DialogFlow ( https://console.dialogflow.com )
GCP (Google Cloud Platform) and Service account and Keys
Connecting your BOT/Application to Syniverse Connector Service
The service will consist of two major parts - SCG MO Handler and API MT Handler.
Creating a Connector in SCG
Creating a MS Azure Connector
Create a MS Azure connector (Request)
curl -X POST
https://api.syniverse.com/scg-external-api/api/v1/connect/connectors -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -H "Authorization: Bearer 8f8a41a5766eff1641a54e92tyi6f95" -d '{"type":"AZURE_BOT_DIRECT_LINE","sender_id":"Uu4txaiKbAWjMN8427QEM2","credentials":"ZrVkDm7_F24.cwA.BEs.Sz0w9A3HT1jhIo67glv8W4wz73y6J_Hd810FP6eFTpQ","external_id":"Test123"}'
Where:
BOT type: AZURE_BOT_DIRECT_LINE
Sender ID: Uu4txaiKbAWjMN8427QEM2 (SMS-Capable Sender ID)
Credentials: Your MS Azure Bot Secret Key
External ID: Optional unique identifier
Response
You will receive a <ConnectorID> as response to a successful request.
Creating a DialogFlow Connector
To create a connector in the type field put “GOOGLE_DIALOG_FLOW” and in the credentials field put the content of the json file with the Dialogflow/GCP keys, properly escaped so can be put in JSON string. For example:
Please note that all quotes (") and all back slashes (\) in the key file content need to be escaped by a backslash, like this - \" or \\
Create a DialogFlow connector (Request)
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/connect/connectors \
-H 'Authorization: Bearer 3f233185-6357-3bd1-b286-14908d21f369' \
-H 'Content-Type: application/json' \
-d '{"type":"GOOGLE_DIALOG_FLOW","sender_id":"cEeua7AU15nWb8c2o8TjLo","credentials":"{ \"type\": \"service_account\", \"project_id\": \"kolanator-9600e\", \"private_key_id\": \"de59b6b44e99ae45068ac0892a7657d46904bbab\", \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBPBzgaldPc9n7\\nUdakd+2xsY0L7zQsw6B/EcmpOGMBBCNSM7wsbluQZK806L5s/Tp0dy15r1nvAFBE\\nMjfjd3jerf5F4RlOf+idwvnE7SitkGASMV9LuwgTdnk0d3yGibchdSTcTpsvCGog\\njHlXghGH2yAUz2DZLcZEIebtYXi9Z45g4/mrQahVPdI6+MIMW7rcD90ZcM6sa6eH\\njoKEK52l8QGLVyLFSdLeVfX1xfuwjdAXlKpHuRPY7G8NdPjcIO9RB7zc73myvRge\\nAiPQZAFIQFMkfWkf5YezUfLh+0VNQb4n9PKbxJCnB+XLwq+odeg9NWD5ay1jtwou\\n8dtN4TjxAgMBAAECggEAFDXb1VL5/8rfrSwBlaEfgLrPxERIAjiRxEiRfXvyyuvq\\nX9IeZ81BEWiedJu1MwQHRaAjZvtCnj87pe5UrxtTToMHObrR4UZ6h2mZoxGk9AZK\\nLgzw6SROM27sPWMT6KRlvX+Zk9pkp7YrF21p0Y++kqWGBPctq3lgp8ad9wz/Slvo\\nOtJ9cRbSpIMMrxqRwZN2fg/wdzRNd/crRhvSGin+PIhafTQfAcHzHHvdE+EBUqjH\\nrr7uvtBawWaWXM6mwff07ThxLYMr+3ChLLoVe4UsBfV/QECT3wrz3WyP21KL3RrG\\nnVGAEwGguKc3Dk2Lg9XpR5BHg60ovRx7Dj9UcNF0qwKBgQDwiPB0kyPJl33JZ9uN\\n3Nj+wNt/Em5n5kNYsOBUSteM6MyNGwsQjomClHQNMrxyxqfrY4pamvqohOdERMMD\\nyqilpKW2fFeoQS9miviQclucCpmAPX7faqoZOHkiVZOd98L8bEG8oHHpidXGfme3\\n7ozH26vkTxIwzSTVqVZgqontxwKBgQDNqKRjjZC+N67sAVKKqKiVizaDhOYHhv9P\\nVRlSxO49kuYVVJ5NkF5kjV7o5vZxTcMSkLlEWWYNS7dX4qHzjRn9GpnYSrtHrqs7\\nPlK2nqN69CHDxGXkpSkY5vPhmh15XzgRaTtiezZtlop6rDb9bRuY/xYUX6CCv/G3\\nOv2owciDhwKBgQDVzRLWu9cKoFJZjKxWC6EByFESQULLrZvdINM1eZThFiiDoC8U\\nl23ZGLWS6a8h4jxt+XuID8uPsRqTzv78xs1i9tepPhr4XoCQiCRq2ItfRvisSX0V\\nf40Uf+MERsbAmfLCRkOkM4UtTawsFD2C+1I9b5/5fuMvZ5k/JZa2s7+IDwKBgQCG\\nqqFKVw6qoAe4nn0QMrSBh/EgWcvOrgVMS2sTmcRvKVvkJ86o95n3ueKmG2bQdpz/\\n8Sh/qxJ6LlRWBh8KPiEAbYTD7tuHasbROlQrJOHjxyy85kPaXpP0rHaSCbq3GTS7\\noe6y4/+V7veqsE4p0GI74vzwRlXyiAGde9FRyeKkzQKBgA0W1Itb5gMjdHTdPsx+\\nfeef/99hI8GISSHVc1npNgrsOIOlHsOt//zMRLHPtJarZ3mKzKkSz4+VqPLbmlK5\\nIMMvcBmH9O9UAcoxWCG6bBn9XZ9PsWjtDnR6DWgMoh67NaiQ/UMXOz25Bp/ludN/\\nHbD1q8SOJKUDyAZqCxAMMlt5\\n-----END PRIVATE KEY-----\\n\", \"client_email\" : \"[email protected]\", \"client_id\": \"112680765748998725263\", \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\", \"token_uri\": \"https://oauth2.googleapis.com/token\", \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\", \"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/[email protected]\" }", "external_id":"my-df-to-rcs-connector"}'
Where:
BOT type: GOOGLE_DIALOG_FLOW
Sender ID: cEeua7AU15nWb8c2o8TjLo (RCS-Capable Sender ID)
Credentials: Your GCP/Service account credentials
External ID: Optional unique identifier
Response
You will receive a <ConnectorID> as response to a successful request.
Note that once your Sender ID has been configured for your Bot service, a MO Handler in the Sender ID properties will be changed to <SCG_CONNECT>. This means that all MO messages to the Sender ID will be forwarded to your BOT. It is therefore recommended that your Sender Address is dedicated to this service and not shared with any other application that is required to receive MO (Mobile Originated) messages
Interacting with your Bot
Send a MO (Mobile Originated) message to your Sender Address which will be passed to your BOT
If your BOT responds, the messages will be delivered to the Mobile device
Other activities you can invoke on the connector service
List a Connector
curl -X GET https://api.syniverse.com/scg-external-api/api/v1/connect/connectors/<ConnectorID > -H 'Cache-Control: no-cache' -H "Authorization: Bearer 8f8a41a5766eff1jk1a54e920d16f95"
List all your Connectors
curl -X GET https://api.syniverse.com/scg-external-api/api/v1/connect/connectors -H 'Cache-Control: no-cache' -H "Authorization: Bearer 8f8a41a5766eff1641a54ji20d16f95"
Update a Connector
curl -X POST https://api.syniverse.com/scg-external-api/api/v1/connect/connectors/<ConnectorID> -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -H "Authorization: Bearer 8f8a41a5766eff1641a54yu20d16f95" -d '{"sender_id":"my-updated-sender-id","credentials":"update-credentials","external_id":"changed-id-assigned-by-me","version_number":"1"}
Delete a connector
curl -X DELETE https://api.syniverse.com/scg-external-api/api/v1/connect/connectors/<ConnectorID> -H 'Cache-Control: no-cache' -H "Authorization: Bearer 8f8a41a5766eff1641a54uj20d16f95"
For more information on the API endpoints for the Connector service, please visit our API reference page on the Developer community portal
FAQ
Q: Does the connector service support BOT services hosted on Amazon Lex?
A: No. Please check back with us on future releases
Q: How many messages per sec can the service support?
A: Default throughput for a connector service is 30 MPs.
Q: Can I configure multiple sender IDs for my BOT service?
A: Yes, however a Sender ID can only be assigned to 1 Connector
Q: How many connectors can I create
A: You can create as many connectors as you want. However, please note that each connector can only have one unique Sender ID.
View ArticleThe SCG Unsolicited Opt-out feature is an service that when provisioned on a numeric sender ID (Longcode, shortcode, Toll-free number) allows the SCG consent management service to blacklist any mobile number that sends a STOP MO Keyword (Opt-Out) to that specific sender ID.
This feature can be added to new Sender IDs via the Purchase API. Please note that all of our pre-provisioned Sender IDs automatically comes with this feature enabled. To add to an existing Sender ID, customer should contact Syniverse customer service or their account manager.
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 54aa5e7c-4a95-30c0-a048-fe5dxx5914ca \
-d '{"name":"Kolanator_Test_Code_55555","class_id":"COMMERCIAL","type_id":"SHORTCODE","address":"55555","country":"USA", "consent_managed_by":"SCG_UNSOLICITED_OPT-OUT","register_number":"false","capabilities":["SMS"],"billing":{"receipt": "Syniverse-1","expiration_date":"02.4.2019","company_name":"Kolanator","company_id":"0000","authorized_user":"Kola L","phone":"+18131111111","email":"[email protected]","message_type":"SMS","description":" SMS Messaging campaign ","shortcode_type":"NUMERIC","campaign_type":"TRANSACTIONAL","campaign_website":"www.kolanator.comom","campaign_discovery":"website", "country": "USA","expected_date_of_service": "02.4.2019","use_case": "Messaging Campaign","estimated_volume":"1000000"}}'
Provisioning of Opt-out Keywords and STOP MTs
Once you shortcode has been provisioned with the Unsolicited Opt-out feature, you now need to have an Opt-out keyword configured. This will be done by Syniverse, but you will need to provide the following information:
Opt-out keyword: This is the keyword your users will send to your sender address. Values could be:
STOP
END
QUIT
CANCEL
Opt-out Message: This is also known as the STOP MT. It is an auto response message sent to the user's mobile number after they send in an Opt-out keyword letting them know they will no longer receive a message from you. e.g. " You will no longer receive a SMS message from Kolanator Enterprise"
All subsequent MT messages from that specific sender ID to the specific mobile number will be blocked by SCG until a non-STOP MO is received from the mobile number.
Customers can list the blocked number's consent status for a particular sender ID. (Note: This API returns a default of 50 records but can always adjust the “offset & limit” values in the API to retrieve the next 50 records)
Request:
curl -X GET -H 'Authorization:Bearer xxxxxxxxxxxxxxxxxx' -H "Content-Type: application/json" https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses/?sort=created_date&offset=0&limit=50&consent_status=OPTOUT&sender_id=ilPuJiyfRTa5RnU74u4xZwer
Result:
{"list":[{"application_id":304,"company_id":27700,"created_date":1468551142734,"last_updated_date":1468552156303,"version_number":3,"id":"PFfztXT8tnojPp4pPD6952","address_type":"LONGCODE","address":"+18313254152",
"sender_id":"ilPOJiyfRTa5tnU74u4xZw","consent_status":"OPTOUT"},{"application_id":304,"company_id":277,"created_date":1471127700553,"last_updated_date":1478196942808,"version_number":3,"id":"yPqRWKuXiXpB7NrXRCpWQ5",
"address_type":"LONGCODE","address":"+14085555555","sender_id":"ilPOJiyfRTa5RnU74u4xZw","consent_status":"OPTOUT"}],"offset":0,"limit":2,"total":2}
View ArticleTo create a digit collector in an active voice call, follow the steps below
1. Create an active voice call
Request:
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/calling/calls \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"from": "USfmJmPpEw4uXRjdQfN9J4",
"to": "+14085551212"
}'
Response: {"id": "dX9qqkH0b2UPEBL0WBsCz6"} - Active call ID
2.Create Digit collector
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/calling/calls/dX9qqkH0b2UPEBL0WBsCz6/digits_collector \
-H 'Authorization: Bearer <Token>' \
-H 'Content-Type: application/json' \
-d '{"max_digits":"10","terminating_digits":"*","timeout":"15","prompt":{"sentence":"Hello, please type your passcode digit", "loop_enabled":true, "gender":"male"}}'
Response {"id": "9M5HBv1LIXTv1BLDCz6iL1"} - collector ID
Webhook Events:
Active Voice call
{
"topic": "SCG-Voice-Call",
"attempt": 1,
"event": {
"fld-val-list": {
"reason_code": "200",
"previous_state": "STARTED",
"company-id": 1512,
"external_call_id": "",
"call_price": 0.0175,
"new_state": "ACTIVE",
"to_address": "+14085551212",
"reason_description": "SUCCESS",
"from_address": "+16282222222",
"application_id": 1764,
"call_duration": 60,
"call_id": "dX9qqkH0b2UPEBL0WBsCz6"
},
"evt-tp": "call_state_change",
"timestamp": "2019-05-23T22:23:35.429Z"
},
"event-id": "TfE426OOR423QyKcLED7iw"
}
Digit Collector event
{
"topic": "SCG-Voice-Call",
"attempt": 1,
"event": {
"fld-val-list": {
"reason": "TERMINATING_DIGIT",
"company-id": 1512,
"collect_id": "9dnDlyHA2dcXFa6zIeGG15",
"external_collect_id": "",
"digits": "58052",
"call_external_id": "",
"application_id": 1764,
"call_id": "dX9qqkH0b2UPEBL0WBsCz6"
},
"evt-tp": "collector_state_change",
"timestamp": "2019-05-23T22:23:48.229Z"
},
"event-id": "XghpT6ZeSFS93ecFPoQCtA"
}
For more information, check out the API reference: https://sdcdocumentation.syniverse.com/index.php/sms-mms/api-reference/explore-api-reference#tag/Digits-Collector
View ArticleSending DTMF in active call can be used to support a variety of voice calling use cases.
For example:
Make a Voice call and need to access a recipient via an extension
Need to send a DTMF during a call to initiate access.
How to send DTMF during an active call
1. Create a Voice Call
Request
curl -X POST \ https://api.syniverse.com/scg-external-api/api/v1/calling/calls \
-H 'Authorization: Bearer b505913a-747e-3117-aae8-hu41f33bcabd' \
-H 'Content-Type: application/json' \
-d ‘{“from": "USfmJmPpEw4uXRjdQfN9J4","to": "+14085551212"}'
Response
{
"id": "lVq5omzMQUW1vVlenYGUi5"
}
2. Send DTMF in the Active call initiated above
Using the CallID < lVq5omzMQUW1vVlenYGUi5> received in the response of the Create call request:
curl -X POST \ https://api.syniverse.com/scg-external/api/api/v1/calling/calls/lVq5omzMQUW1vVlenYGUi5/play_dtmf \
-H 'Authorization: Bearer b505913a-747e-3117-aae8-6841f33bcabd' \
-H 'Content-Type: application/json' \
-d '{
"dtmfText": "12345#"
}'
Parameter Description
Parameter: dtmfText, String containing the DTMF characters to be sent in a call. Allows a maximum of 50 characters.
{
"dtmfText": "12345#"
}
The digits will be sent one-by-one with a marginal delay. Valid characters are given by the regular expression[A-D0-9#*,wW]+.
- The,and lowercasewcharacters introduce a half-second pause into the DTMF sequence.
- TheWcharacter introduces a one-second pause.
Example 1: The DTMF string1WWW,59#will send a1, wait 3.5 seconds, then send59#in quick succession.
{"dtmfText": "1WWW,59#"}'
Example 2 : Send a '1', then '2', then '1', then '#' with a wait time of 1.5 seconds between each character
{ "dtmfText": "1Ww2Ww1Ww#" }
View ArticleMessage link tracking and Conversion
Messages that contain URLs can also contain a keyword(#track)that will trigger a URL replacement in the message. When an end user clicks the URL, the Syniverse SMS API service will notify the Customer that a "click-thru" and then a "conversion" event has taken place.
A conversion is a record of a response from a user to a message, not represented by a direct reply, but rather by recipient interaction (behavior.) For example, following a URL provided in an SMS message is a conversion event. Replying to a message can also be a conversion event. Each conversion event is associated with a recipient disposition (e.g. whether the response was positive or negative.) Conversion events can also be posted by the enterprise/application if these events originate outside of the Syniverse Communication API service’s awareness. (In that context, we provide an optional service that customer can subscribe to which can still track this and provide reporting and analytics based on them.)
How this works:
Our Communication Gateway offers Link Tracking capabilities for Message Requests with a URL shortening service. URLs within messages can be flagged for tracking. For tracked URLs, the service will replace the URL with a shortened URL (2.lnkme.net), that points to the link tracking service. When the end user navigates to the tracked URL, the link tracking service will update the message status to "CLICKTHRU" to show that the link was clicked. There will also be a Message State Change event generated and sent to any delivery configuration endpoints for this application.
In order to flag a URL to be tracked, the url is passed as an argument to a #track directive in the message body.
Here is a sample message request with a tracked URL:
Request:
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests \
-H 'Authorization: Bearer 3c5a336dfhu9d3f3e4d129a749b0f307' \
-H 'Content-Type: application/json' \
-d '{"from":"address:18775551212","to":["+14085551212"],"body":"Hello Kola, thanks for your patronage, please visit us at #track(\"http://www.syniverse.com\") for new information"}'
Here is the message received on the Handset:
Hello Kola, thanks for your patronage, please visit us at https://2.lnkme.net/XYaP7o for new information.
Please note that when using the message console UI, be sure to remove the escape in the sample url above.
State Event for Messages:
Your application will receive several event state with a final one of “CLICKTHRU” assuming you have a webhook setup. The CLICKTHRU state will be part of several fields in the JSON posted to your application via your webhook and this state will only be received once the end-user clicks on the shortened link in the message
Sample JSON for a CLICKTHRU Event State:
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"previous_state": "DELIVERED",
"message_request_id": "9E0qhwPclVXnqMjbaYF4J5",
"message_id": "uFAbXDeSXGMzgK5Qoxw5g2",
"to_address": "+14085551212",
"has_attachment": false,
"reason_description": "SUCCESS",
"application_id": 631,
"reason_code": "200",
"sender_id_alias": "Gladiator",
"company-id": 92,
"sender_id_id": "EjihJOXWJE24OhXleFXMG3",
"external_message_request_id": "",
"new_state": "CLICKTHRU",
"fragments_count": 1,
"from_address": "18775551212",
"mt_price": 0.0095
},
"evt-tp": "message_state_change",
"timestamp": "2018-08-10T18:42:27.059Z"
},
"event-id": "0nJNzMB5TjmdBQcTtiyW5w"
}
View ArticleEvent Manager will try to retry delivery if the first delivery fails in the following cadence:
First 30 seconds: 1 delivery retry
Next 1 mins after previous step: 1 delivery retry
Next30 minutes after previous step: 1 delivery retry
Next 60 minutes after previous step: 1 delivery retry
View ArticleSolution Overview
Syniverse Toll-Free Messaging Solution offers a convenient communication channel that enables businesses to engage directly with their customers through SMS and MMS (multimedia messaging). Through the use of a pre-provisioned Toll-free number or a business's existing branded toll-free 1-8xx number, customers can initiate a dialogue with businesses to address their questions or concerns, request account updates, and inquire about products and services. Businesses can then respond to their customers, enhancing loyalty and building brand credibility while respecting customers’ time and availability.
How it works
Content policy
Use Cases
Below are examples of ways to leverage Syniverse toll-free messaging solution to extend your reach, enhance customers’ satisfaction and loyalty, and increase brand engagement:
Security & Verification - Send OTP (One-time passcodes) using Toll free messaging, verify and authenticate consumers using their mobile device.
Customer Service - Optimize your consumer engagement process by introducing text message interactions. Consumers can inquire about orders, appointments or receive latest information via Toll-free messaging
Event Notification - Send alerts and notifications for appointments, reminders or event-based notifications like delivery confirmations, delays etc
Content Compliant Marketing programs
Toll-Free Messaging Program Onboarding
Syniverse communication gateway offers Enterprise customers with valid programs and use cases the ability to engage end-users via our SMS API resources or the use of our SCG Message Console by leasing or migrating Text-enabled Toll-free numbers. Customers are able to lease one or more toll-free numbers from Syniverse to use for SMS messaging.
It is critical that it is understood that Toll-free messaging must comply with TCPA rules with regards to Opt-in and Opt-out end-user consent. As part of the onboarding, customer must be able to provide upon request the following information to ensure compliance:
A Valid Use Case
Process to Opt-In (opt-in work flow with screen shots)
Sample Message Content
Terms of Service
Privacy Policy
Failure to comply with TCPA rules or violation of Toll-free messaging, may result in your messages blocked and may result in fines if a complaint is made to the authorities.
Why Syniverse Toll Free Messaging
View ArticleWhen sending MMS via SCG API, the current delivery throughput to the operators is a max of 20TPS
View ArticleThe Syniverse Cloud Messaging (SCG) services is an Omni-channel communication platform that allows customers to engage their end-users over a wide range of communication channels. To enable the functionalities, a Sender Address is required which serves as a unique identifier for the Business or its Campaign. Sender Address can either be purchase or requested.
Shortcode Sender address whether it be in numeric format or Alpha format needs to be requested and provisioned before it can be used on the Cloud Messaging platform. Customer need to work with their assigned Implementation Manager or Customer Success manager to trigger the flow.
Once the Implementation process has been completed, Customer needs to follow the process below to request and activate their Sender address in their account
How to request a Shortcode (Numeric/Alpha) Sender Address
Prerequisite
Voice and Messaging Service offering
A valid Syniverse Application
A valid Postpaid account
Requesting a Shortcode (Numeric/Alpha) Sender address
Via SCG UI
Log in to the SCG UI/Messaging Console via the Syniverse Developer Community portal
Click on Voice and Messaging Console
Select your Account if prompted
In the SCG Messaging Console, navigate to the “Messaging Account” in the left nav and click on “Sender Address”
Customer clicks on button and selects the Sender address type and Country.
If customer is migrating or already has shortcode provisioned in Syniverse and has the Shortcode number handy, Customer should click the link on the page below.
Next step is for the customer to complete the Shortcode request form. For shortcode migration or if you are looking to provision your existing code, please make sure to upload the receipt for the shortcode. If you don’t have this info, please reach out to your Syniverse account rep for assistance. Please note that default subscribe consent for shortcodes on the Syniverse Communication gateway is “User”. Additional charges and subscription apply to the use of “Syniverse Managed” consent.
8. Once the form has been completed, submit the request and a Syniverse Implementation manager will contact you on next steps. Please note that for new Shortcodes that requires Carrier approval, implementation could take up to 8 weeks.
VIA API
If provisioning a Shortcode and you already have the Shortcode value:
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name":"Kolanator Campaign2","class_id":"COMMERCIAL","type_id":"SHORTCODE","address":"445557","country":"USA","consent_managed_by":"USER","register_number":"false","capabilities":["SMS"],"billing":{"receipt": " Kola Receipt","expiration_date":"12.13.2028","company_name":"Kolanator","authorized_user":"Kola","phone":"+14086881111","email":"[email protected]","message_type":"SMS","description":" Messaging SC Production campaign ","shortcode_type":"NUMERIC","campaign_type":"TRANSACTIONAL","campaign_website":"www.kolanator.com","campaign_discovery":"Website", "country":"USA","expected_date_of_service": "","use_case": "Alerts","estimated_volume":"1000000"}}'
If you are provisioning an ALPHA sender Address, make sure you use the parameters & values as outlined:
"type_id" = SHORTCODE
"address" = Your ALPHA value
"country" = Country where you Alpha sender is registered for
"shortcode_type" = ALPHA
View ArticleDisallowed Content Policy for Toll-Free number messaging
Syniverse Communication gateway provides access to use text enabled toll-free numbers to engage end-consumers as part of A2P SMS messaging. Toll-free SMS messaging like any other messaging protocol must comply with TCPA rules with regards to consent and cannot be used to send unsolicited messages or content that violates carrier rules or local laws.
The following categories have been attributed to be harmful or deceitful to the end consumer and will no longer be supported on Toll-Free Telephone Numbers.
High-Risk Financial Services
Payday Loans
Short Term- High Interest Loans
Auto Loans
Mortgage Loans
Student Loans
Get Rich Quick Schemes
Work from Home Programs
Risk Investment Opportunities
Debt Forgiveness
Debt Consolidation
Debt Reduction
Credit Repair Programs
Phishing
Fraud or Scam
Deceptive Marketing
Syniverse Customers are expected to enforce restrictions on their own applications to prevent these types of content being sent to through the Syniverse Interface. All messaging traffic must comply with TCPA rules with regards to consent from end-users. If upon investigation or complaint from our Operator partners it is determined that your traffic contains at least one of the categories restricted above, Syniverse will request that you stop sending the traffic immediately. Continuing to send such messages will result in violation of our acceptable user policy and or our general terms of service which could lead to the suspension or termination of the use of our Toll-free numebers and your access to our network.
View ArticleRegistered Account owners with a payment account (Prepay/Postpaid) can purchase any number of pre-provisioned sender address or request a Sender address for the Voice and Messaging Service offering as well as for the 2-Way Chat solution.
Prepay customer must ensure that they have purchased sufficient credits amount to cover the initial cost and subsequent monthly cost of leasing a Sender Address
Syniverse has the following types of pre-provisioned Sender address with following the capabilities:
SMS
MMS
Voice
Sender Address can be of the following type:
Toll-free
Longcode
Shortcode/Alpha
Purchasing a Pre-provisioned Sender Address
Once you've determined the type of Sender Address you want to purchase, you have 2 options to complete this:
Using the SCG Purchase API
To use the SCG purchase API, please familiarize yourself with the SCG API resource document which can be found at https://sdcdocumentation.syniverse.com/index.php/sms-mms/api-reference/explore-api-reference#tag/Sender-ID/paths/~1messaging~1sender_ids/post
Steps:
List the available Sender Address based on the ownership, country and type e.g.
Request:
curl -X GET -H "Authorization: BearerToken" -H "Content-Type: application/json" -dhttps://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids? offset=0&limit=20&ownership=PREPROVISIONED&type_id=TOLLFREE&country=USA
Sample response:
},
{
"created_date": 1492124130128,
"last_updated_date": 1492124130128,
"version_number": 1,
"id": "TfNwFsuJWdNVrRrAdSgu05",
"name": "SCG_TFN_18773123230",
"ownership": "PREPROVISIONED",
"class_id": "COMMERCIAL",
"type_id": "TOLLFREE",
"state": "ACTIVE",
"address": "18775551212",
"country": "USA",
"consent_managed_by": "USER",
"applied_charges": [],
"capabilities": ["SMS"]
},
Each Sender Address type has a Sender ID associated. Once you've determined which of the sender IDs you wish to purchase, make a POST call to the purchase API resource using the Parent Sender ID of the number you are purchasing:
Request:
curl -X POST -H "Authorization: Bearer Token" -H "Content-Type: application/json" -d '{"parent_id":"TfNwFsuJWdNVrRrAdSgu05", "purchase_form":{"country": "USA","expected_date_of_service":"10.14.2017","use_case":"test alerts","message_type":"SMS","estimated_volume":"10000","company_name":"Kongo LTD","company_id":"12345","authorized_user":"Kola","phone":"140812125555","email":"[email protected]","receipt": "none","expiration_date":"10.14.2019","description":"Customer reminder alerts", "campaign_type":"transactional","shortcode_type":"Random","campaign_website":"www.joecompany.com","campaign_discovery":"website"}}
https://api.syniverse.com/scg-external-api/api/v1/messaging/sender_ids/purchase
Sample Response:
{
"id": "8C4JzBXOvxqzfpRWceMoH8"
}
You have now purchased a Toll-free sender address : 18775551212. The Sender ID for this new Toll-free number will be listed in your account
Using the SCG UI :
Log in to the SCG UI
Navigate to the "Messaging Accounts" menu on the left side Menu tree
Select "Sender Address" and click on "Purchase or Migrate Sender Address" contact sales.
Select the Country, Currency and Sender Address Type that you wish to purchase and a time-frame for your when you want it to be activeand click Next. Please note that Sender Addresses are country specific. Make sure you select Sender addresses for the specific country you are looking to send messages to.
The available Sender Addresses will be displayed and you can select the number(s) you wish to purchase by clicking the Sender ID box(es) and then click next
Please note that if you are purchasing a Shortcode/Alphacode or Toll-free numbers, completion of a purchase form is required. In the case of a Shortcode/Alpha, additional approval and program/campaign approvals may be required by the carriers. In the event that this is the case, your transaction or request of the Shortcode would be in a pending implementation stage till all necessary approvals are given.
Once you've completed the form, click "Submit". Your Toll-free number or Longcode is now ready to use. You can view them under your Sender Address menu.
For Pricing information, be sure to visit our developer community portal or
View ArticleProperty Manager
Customers using the Syniverse 2-Way Chat Service can create Property Managers as a user of their tenant that has more advanced capabilities than an agent. A Property manager is an authority over a particular property. Below is a list of activities a property manager can perform
Can do everything an agent can do
Create New Agents (User Logins)
Assign Agents to a property
The can delete, view messages across the Property
Create a Property Manager
You have to be a Global Manager to create a Property Manager.
Login to your tenant with your Global Admin credentials
Navigate to the Administration tab
Select the sub-tab "Property managers"
Select
Fill in the form below with the necessary details. A property manager can only be assigned to one property
Click Save
If you need to change an Agent to a Property Manager, you will need delete the Agent and re-create as a Property Manager.
View ArticleThe SCG Cloud Messaging APIs offers an option attribute on its messaging API endpoint that allows customers to have the system perform a number verification for validity before deciding if the message should be sent to the recipient or not.
This feature allows customers to determine if a number is a landline or mobile number or an invalid number which helps to avoid sending messages to invalid numbers.
How to Send a Messaging with number verification flag
To send a SMS message using the number verification flag, include the following attribute and value in the message submission
Set "verify_number" : " true" if you want to perform a verification
Set "verify_number" : " False" if youdon'twant to. You also choose not to include the atriibute at all
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages\
-H 'Authorization: Bearer <Token>' \
-H 'Content-Type: application/json' \
-d '{"from":"address:222222","to":["+14085551111"],"body":"TEST MESSAGE", "verify_number":true}'
If you have your webhook setup to receive Delivery confirmation, can expect to see the following field in your Delivery receipt event if the number valid
"number_type" : "M" or "VL", L
where M = Mobile, VL= Virtual Longcode, L = Landline
Sample DR Event
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"previous_state": "QUEUED",
"message_request_id": "44Sb8nOEQBGL4uCkxmVnT5",
"message_id": "gYSpaGHxb5X6OqStyGICy7",
"to_address": "+14085551111",
"has_attachment": false,
"reason_description": "SUCCESS",
"number_type": "M",
"application_id": 1764,
"reason_code": "200",
"sender_id_alias": "RexWQXiD7pF7Kzvepjkio",
"company-id": xxxx,
"sender_id_id": "RexWQXiD7pF7Kzvepijkio",
"external_message_request_id": "",
"new_state": "SENT",
"fragments_count": 1,
"from_address": "222222",
"mt_price": 0.0125
},
"evt-tp": "message_state_change",
"timestamp": "2019-02-05T18:25:22.76Z"
},
"event-id": "CLIxCr7ZRfeBUHHYP3eZQQ"
}
In the case of the number not being valid, the DR event will have the failed response with a reason description, see below:
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"previous_state": "QUEUED",
"message_request_id": "N6xNcTYqtkFXr3XTzsRmH1",
"message_id": "N6xNcTYqtkFXr3XTzsRmH1",
"to_address": "+14085551111",
"has_attachment": false,
"reason_description": "Invalid Recipient - Validity: true NumberType: L",
"number_type": "L",
"application_id": 4334,
"reason_code": "1002",
"sender_id_alias": "RexWQXiD7pF7Kzvepikol",
"company-id": 1512,
"sender_id_id": "RexWQXiD7pF7Kzvepikol",
"external_message_request_id": "",
"new_state": "FAILED",
"fragments_count": 1,
"from_address": "222222",
"mt_price": 0
},
"evt-tp": "message_state_change",
"timestamp": "2019-02-05T21:07:42.393Z"
},
"event-id": "UZEbBkKjT0_wXTK9Jd_WFw"
}
View ArticleSyniverse Cloud messaging service has introduced a new Messaging API endpoint that allows better throughput performance for Customers that are sending SMS or MMS messages to Single recipients at a time.
Direct Message end point : https://api.syniverse.com/scg-external-api/api/v1/messaging/messages
The Direct Message API has some of the same attributes as the existing /message_request API endpoint. The Direct Message API end point can be used to
Schedule Message to a single recipient
Send one to one messages on any channel ( SMS, MMS, FB messenger, WeChat, etc)
Suitable for 2- way messaging conversations
Sample Request using Direct Message API:
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer <Auth Token>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '{"from":"address:18322222222","to":"+14085551212","body":"This is a Direct Message API test to Kola"}'
View ArticleSupported Characters
The type of characters used in a SMS Message will determine the type of encoding which needs to be used in the SMS message. The Syniverse Communication Gateway (SCG) Messaging API automatically detects the encoding required for the characters used, which then allows us to support the delivery of SMS in most languages. We have full support for Unicode which allows us to support a wide range of languages including Spanish, French, Chinese etc over SMS. All you have to do is make sure you compose and send in UTF-8 format and our systems takes care of the rest.
Basic Character Set
The following characters will be sent as plain text 7-bit encoding, which allows us to send up to 160 characters per SMS message.
@ SP 0 P p
_ ! 1 A Q a q
$ “ 2 B R b r
# 3 C S c s
4 D T d t
\% 5 E U e u
& 6 F V f v
‘ 7 G W g w
( 8 H X h x
) 9 I Y i y
LF * : J Z j z
+ ; K k
, < L l
- = M m
. > N n
/ ? O o
Extended Character Set
The following characters are also available, but they take up two characters in the SMS message rather than one
|,^,,{,},[,],~,\
Other Characters
If other characters are required for different languages, Unicode encoding will be used. This allows up to 70 characters per SMS message.
Long /Concatenated Messages
The message body can contain up to 1500 characters. Depending on the characters used in the message, this will equate to the following numbers of SMS messages. The Syniverse Messaging service will support up to 10 SMS concatenated messages or fragments. It is very important to note that each Fragment is billed at the agreed upon message rate.
Using 7-bit Characters:
Each concatenated message or fragment with a 7-bit encoding has a maximum of 152 characters
Message Length
Number of Fragment
1 - 160
1
161 - 304
2
305 - 456
3
457 - 608
4
609 - 760
5
761 - 912
6
913 - 1064
7
1065 - 1216
8
1217 - 1368
9
1269 - 1520
10
Unicode Characters:
Each concatenated message or fragment with a unicode encoding has a maximum of 60 characters
Message Length
Number of Fragments
1 - 70
1
71 - 132
2
133 - 198
3
199 - 264
4
264 - 330
5
331 - 396
6
396 - 462
7
463 - 528
8
529 - 594
9
595 - 660
10
View ArticleThe Messaging API supports upto 10K phone numbers in the "to" field for sending SMS and MMS in one single request. Please note that if you need to send more, it is recommended that you use the Contact group feature
View ArticleCustomers have the option to setup a HELP and STOP Keywords with corresponding MT messages using the Messaging API or via the Messaging Console.
Creating a STOP Keyword
curl -X POST -H "Authorization: Bearer d17f79e76e30d7a0f05e6444b0bbc77a" -H "Content-Type: application/json" -d '{"name":" Music STOP Keyword","case":"SENSITIVE","value":"STOP","sender_id":"yYAhNMl4TDuh06Y7fN0zig", "valid_to":"2020-01-07T21:52:34.473Z","valid_from":"2017-01-07T21:52:34.473Z", "reply_template":"You will no longer receive messages from Syniverse"}' https://api.syniverse.com/scg-external-api/api/v1/messaging/keywords -v
Creating a HELP Keyword
curl -X POST -H "Authorization: Bearer d17f79e76e30d7a0f05e6444b0bbc77a" -H "Content-Type: application/json" -d '{"name":" Music HELP Keyword","case":"INSENSITIVE","value":"HELP","sender_id":"yYAhNMl4TDuh06Y7fN0zig", "valid_to":"2020-01-07T21:52:34.473Z","valid_from":"2017-01-07T21:52:34.473Z", "reply_template":"Please contact us at www.syniverse.com "}' https://api.syniverse.com/scg-external-api/api/v1/messaging/keywords -v
View ArticleSDC supports two ways to refresh tokens. The first one is through the SDC portal and the second one is programmatically via APIs. I have described both the methods below.
Token Refresh Through SDC UI
Please follow the following steps on the SDC UI:
Log into the SDC UI and go to the Applications page.
Select the Application for which you want the token to be refreshed.
Click on the gear icon at the upper right corner of the Application screen.
Click on the “Auth Keys” tab of the Application screen.
In order to re-generate the token, you need to provide the following parameters:
The Token Expiration duration. Any value <=0 results in a non-expiring key.
Select the unit associated with the value. Possible values are “Milliseconds”, “Minutes”, “Nanoseconds”, “Seconds”, “Microseconds”, “Hours” and “Days”.
Click on the “Re-Generate” button.
A new token is generated and displayed on the UI under “Access Token” field.
Token Refresh Programmatically
Please follow the following steps to refresh the token programmatically. The following API call can be used to refresh tokens:
/saop-rest-data/v1/apptoken-refresh?consumerkey=xxxxxx&consumersecret=xxxxxx&oldtoken=xxxxxx&validity=xxxxxx
The API call requires the following parameters:
Consumer Key -> Available on the Application page under “Auth Keys”
Consumer Secret -> Available on the Application page under “Auth Keys”
Old Token -> Available on the Application page under “Auth Keys”
Validity -> Should be a number with a unit of “Seconds”
The sample https API call example is as follows:
https://api.syniverse.com/saop-rest-data/v1/apptoken-refresh?consumerkey= xxxxxx&consumersecret=xxxxxx&oldtoken=xxxxxx&validity=xxxxxx
The curl API call example is as follows:
curl -X GET -H "Accept: application/json" " https://api.syniverse.com/saop-rest-data/v1/apptoken-refresh?consumerkey= xxxxxx&consumersecret=xxxxxx&oldtoken=xxxxxx&validity=xxxxxx"
The response for the API call is:
{"accessToken":"<New Token>","validityTime":<Time to Expiration>}
Example - {"accessToken":"e6e9b18a-6e62-38fb-9bd4-9aa82e93f654","validityTime":86011}
View ArticleSome US and Canadian Carriers levy a fee per message that is sent and received on their network for A2P messaging. These fees are passed on to each Customer as an additional charge for messages that are delivered and received. Below is an outline of the pass thru fees and the Carriers that are applicable.
US
Canada
Carrier
MT Pass-thru
MO Pass-thru
Carrier
MT Pass-thru
MO Pass-thru
T-Mobile
$0.0025
$0.0025
Bell Mobility and Bell MVNOs (Aliant, Telebec, NorthernTel, Virgin Mobile Canada)
CN$0.01
CN$0.01
AT&T
$0.0025
0
Effective July 1st 2018
Rogers (and MVNO Fido)
CN$0.0025
CN$0.0025
Sprint (Virgin, Boost)
$0.0050
$0.0050
Telus and Videotron
CN$0.0050
CN$0.0050
Verizon
$0.0025
0
Freedom Mobile
CN$0.0025
CN$0.0025
Effective Sept 1 2018
US Cellular
$0.0035
0
View ArticleCreate Company
A company contains all of the information about users, accounts and payment methods. A Company is also required before a postpay account can be requested.
Hover over your name, on the top right hand corner of the portal
Select “Company”
Give your Company a name on the box in the left hand side (Please make sure the Company name matches your Company's legal)
On the general tab, click: (This is optional)
Copy the generated invitation code to a clipboard
Share the invitation code with the persons you want to invite to be part of your Company in Syniverse Developer Community
Once you have created your Company, you are now ready to apply/request for a Postpay account
Request Postpay
To request a PostPay Account(Only available for US-based Companies with a Fed TaxID) NOTE: It is recommended you work directly with a Syniverse representative when setting up a postpay account.
Select the Accounts tab
Click:
Give the Account a name
Select if you want to have a Restricted account (only users with specific entitlements can access this account)
Enter First Name and Last name ( Authorized user or Company Admin)
Enter the Email Address
Enter your Contact phone number
Make sure the Company name is the same as in the Tax ID records
Enter a valid Federal TaxID
Enter billing address that matches Tax ID information
Select the “I already have a Syniverse BillingID “ if you’ve already been provisioned for one
Enter the Billing ID if you know it, if not leave blank
Accept and Read the Terms of Service
Click:
Your Request will be in a Pending State until the Postpay application is approved. (Please check periodically for a status update).
If the details you entered do not match, then your request will be rejected. Please make sure that the details match.
View ArticleSyniverse Cloud Messaging service offers SMS services using text-enabled Toll-free numbers for the US market. We have provided a list of operators (See attachment) and supported use cases. Please be aware that not all Operators in the US support A2P (Application to Person) messaging. For more information, you can contact Syniverse Sales @ https://www.syniverse.com/connect-with-us
View ArticlePreviously we showed you how to build a simple application that supported 2 way SMS across multiple countries by routing multiple phone numbers in different countries to a single destination.
Sometimes though you may want to route your SMS to different destinations. For example you may two different campaigns running on different phone numbers, with a different URL defined in your platform for each campaign.
This article will guide you through the process. We assume that you are already familiar with the Syniverse Developer Community and have already completed the SMS Quick Start and 2 way SMS examples.
Example Overview.
For this example we will have set up two different phone numbers and will route SMS sent to these phone numbers to two different destinations. In this case we will be using http://putsreq.com for those destinations.
Steps to set this up
Create your destinations
Set up your delivery configurations
Set up your event subscriptions
Test the set up
Create your destinations
Go to http://putsreq.com and create two buckets, one for each destination. Make a note of the URL for each.
Each bucket will look like this
these instructions
Screenshot showing Putsreq page
Set up your delivery configurations
Following these instructions, create two delivery configurations, one for destination URL you created.
Each delivery configuration should look like this.
Screenshot showing Example Delivery Configuration
Set up your Event Subscriptions
Following, create two event subscriptions, one for each delivery configuration, but with one extra step.
The extra step needed to route SMS based on phone number is to create a matching criteria rule in each subscription.
Set Topic to SCG-Message
Set event type to mo_message_received
Set delivery configuration to one you created in the previous step, using the drop down
Set the matching criteria to to_address contains ‘XXXXX’ where XXXXX is the number you wish to forward the destination.
The matching criteria field will prompt you with the available options for
the field to match on
operators available
matching criteria format
The correct option can then be selected from the drop downs as shown below.
Screenshot showing how to select to_address
Screenshot showing how to select contains
Screenshot showing how to enter number using ‘text’ field
Then repeat the above for the second delivery configuration and use your other phone number in the matching criteria.
Bonus section: Using multiple matching criteria
It is also possible to use multiple matching criteria by using and & or. In the example below we have add an extra criteria to check whether the message contains a certain keyword.
Screenshot showing filtering on number and message content
View Article
Syniverse's Competitors
Recently Asked Questions
Recent Syniverse Employee Reviews
- No vision or strategy. Stuck to the golden past era and expecting that it will magically return without any improvements. Internally just keep reorganizing every year for the past 7 years expecting who knows what
- Nightmare for all the reasons you see in all the reviews.
- Take more workers than VP and directors
- I am finding them to be misleading.
- Frequent changes, lack of vision & clear goals