Omni-Channel Messaging
Documentation /

SMS-MMS User Guide

Using the SMS/MMS Channel

The Syniverse CPaaS offers support for a SMS Channel on a global scale that allow Enterprise customers to engage their users locally and Internationally.

This user guide describes how to use the the Syniverse Communication API service to send SMS and MMS messages. MMS is currently only available is the US on the 4 top tiered Carriers. Please make sure to familiarize yourself with the basic key concepts and practices employed as it pertains to SMS and MMS on this platform by visiting the Omni-channel messaging guide.

For information on API resources for SMS and MMS, checkout our Omni-Channel API Reference documentation.

Prerequisites

To invoke the API or Message console needed to send and receive SMS or MMS, you need to have the following items configured to get started:

  • An Account in Syniverse Developer Community
  • Subscription to the Voice & Messaging Offering ( Your are auto-subscribed to this)
  • A Syniverse Application ( This is how you get your Auth keys)
  • An Initial Account (Test account) with funds or a Postpaid account in Syniverse Developer Community
  • optional Whitelisted recipient number (mobile number) to receive test messages on. ( US and Canada -only)
  • A Carrier approved program or Use case (Please note that this is required in the US/Canada if running a Shortcode or Long Code Messaging Program)

A valid Sender Address that could be in the form of a:

  • Shortcode
  • Longcode ( Telephone number)
  • Toll-Free number ( SMS-only)
  • Alphanumeric Sender Address ( where available)

To purchase or lease a Sender address, please refer to the Purchase Sender ID API resource section of the API reference guide or our knowledgebase article on how to purchase a sender address. For additional information, please reach out to Syniverse Sales.

Related Features

  • Message Templates
  • Message Scheduler
  • Keyword Management
  • Contact Address Book
  • Public and Private Channels
  • Event Services
  • Text Language translate

Sending SMS Text Message

Now that you have all the prerequisites covered, below are 2 simple options to send your first SMS text message:

Using the Syniverse Message Console

  • Navigate to the Syniverse Message console via the SDC portal

SDC_Voice_and_Messaging_Console.png

  • Once in the Message Console, click on the "Send Message" menu on the left Nav bar.

  • The SMS tab is selected by default, so now in the "From" box, you have the option of using a Sender Address you've purchase by clicking on the button or you can select the button to use a Public test channel. For more information on using channels, please see our knowledgebase article on how to use a public channel.

Sending a SMS to a single recipient

When sending to a single recipient;

  • Populate the "To" field of the Send message with the appropriate Mobile number. Bare in mind that the format for the mobile number has to be in E.164 format e.g. +14085551212)
  • Compose your text message in the "Message" field

  • Click to send your message.

Sending a SMS to a Contact

Similar to the above flow, you can send a message to a Contact. A Contact is a recipient that you have stored a recipient address for in the Syniverse Address book in the platform. For more information how to store a recipient address, please visit our knowledgebase portal.

  • Populate the "To" field by clicking on the button to add the recipient you want to send a message to

  • Compose the message text and click send.

Sending SMS to a Contact Group

To Send a message to a contact group, you need to have created a contact group using at least 2 contacts (recipients with the same recipient address format e.g Mobile number)

  • In the "To" address field of the send message, select the button and select the group you want to send a message to.

  • Once populated, compose your message and click the "Send" button to send.
  • The same message will be sent to all the recipients configured in the contact group.

Using the Syniverse Message APIs

Sending a SMS to a recipient

To send SMS message using the Syniverse APIs, you need to make sure you have your application developed to call the SMS API endpoints. Please make sure you familiarize yourself with our API reference guides. It is also important that you have a valid authentication key before invoking the APIs.

There are 2 API resource endpoint for sending messages.

For messages that are for single recipient, it is recommended that you invoke the Direct Message API endpoint. The Direct Message API endpoint is suitable for sending messages to a single recipient for use cases like conversational chats, notifications, alerts, OTPs.

When sending to a group of recipients in a Contact group or more than one recipient in the "To" field, invoke the Bulk Message API resource which gives you more information about the message request and status of the requests.

For more details on the use of the API resource, explore our Omni-Channel API Reference documentation.

Sample Direct Message API

curl -X POST -H "Authorization: {Bearer Token"} -H "Content-Type: application/json" -d '{"from":"yYAhNMl4TDuh06Y7fN0zSg","to":"+14085551212","body":"Hello World"}' "https://api.syniverse.com/scg-external-api/api/v1/messaging/messages"

Important: To get status indication or notification of your messages, you have the option of using the "Outbox" feature in the Message console or the Event management service for API events that can be posted directly as callback to your application. For more information on using Event Manager, please checkout our knowledgebase article on setting up a webhook for receiving notifications and messages.

View Message Status in Outbox

  • In the Syniverse Message Console, navigate to the Messaging menu on the left nav-bar
  • Click on "OUTBOX" to reveal the Bulk and Single message Outbox folders
  • Click on the "Single Message" folder to show your messages and status

  • Double click each message to get more details about the message.

Receive Message Status programmatically

To receive message status programmatically, you are required to setup a webhook in our Event Manager service. When a message is sent successfully, Syniverse will generate a "Delivery Receipt" in the form of a JSON/XML payload. For more information of receiving Delivery receipts, visit our knowledgebase portal.

Receiving a SMS Text Message

In order to receive a SMS text message from a recipient, you must have a Sender ID that is provisioned to receive messages. Syniverse provides 2 options to view/receive messages sent to your Sender ID (MO) Mobile Originated messages

View your received messages in the Inbox

  • In the Syniverse Message Console, navigate to the "Messaging" menu on the left-nav bar
  • Click on "INBOX" to reveal your received messages

 

  • Double click each message to get more details about the (MO) received message

Receiving a SMS in your application

Receiving MO (Mobile Originated) messages in your application programmatically is very similar to receiving Message status. Once you've configured your application with a webhook on our Event Manager, all received MO messages will be sent to your end-point in the form of a JSON/XML. For more information on how to customize your events, please visit our Knowledgebase portal

Sending a MMS Message

Sending a Multi-media message (MMS) is very similar to sending a SMS. The main difference is that a MMS message includes an attachment. MMS is currently only supported on 4 US Operators.( T-Mobile, Verizon Wireless, AT&T and Sprint. It is important to understand that the attachment payload that makes up the MMS have specific content types that are supported by the US Operators. For more information on supported content types and size, please see the Supported MMS content type knowledgebase article for details.

Using the Message Console

  • In the Message Console, similar to sending a SMS, navigate to the "Send Message" menu under "Messaging" and select the "MMS" tab.

  • Input your Sender ID in the "From" field and recipient address ( Mobile Number) in the "To" field.
  • Optionally, include a text message (up to 1000 characters) in the "Message" field.
  • To add your MMS payload, you can select an existing attachment by clicking the button or the button.

Sending MMS using attachment service

Uploading an Attachment for MMS

  • Once uploaded, provide an attachment name for your content. This will be stored in attachment services for 7 days.

  • Click "+Send" to send your message.

Sending MMS using Media URL

Another method to send a MMS is by using a Media Url to link to where your content is stored.

  • Click on the button
  • Add the link to our Content making sure its the complete url to the content. You can add upto 5 media URLs for a message. Please note that the total size of the contents in each URL cannot exceed the total size allowed for a particular message or your message will be rejected.

  • Once the Media URL is attached, click to send your MMS message

Receiving a MMS Message

All MMS messages sent to your provisioned MMS-capable Sender ID can be viewed in the Message Console INBOX. MMS messages are received in the form of an attachment. Attachments can be downloaded via the Mesasge Console INBOX or using the Attachment services API.

Notifications can also be POSTED back to a configured webhook indicating that an attachment is available. To retrieve your attachment programmatically, see the link to a knowledgebase article providing you with a step by step guide on how to download your MMS message


Transaction Events for Messaging

Message Service Events

Transaction events can be sent directly to your application for Messaging related statuses. Status for Outbound messages ( Delivery Receipts) DR and Inbound messaging notifications (MO events) can be setup using the Syniverse Events Manager. The Syniverse Event Manager allows you to configure webhook(s) with callback urls where any number of events can be "posted" to. For more information on setting up a webhook, visit our webhook knowledge base article on this.

Message Service Subscription

Once your webhook as been setup using Delivery configuration, you now need to subscribe to the Event topic "SCG-Message"

  1. Log in to SDC portal
  2. Select Event Manager
  3. Navigate to Subscription from the Event Manager drop down menu
  4. Select New Subscription
  5. In the Topic field, select "SCG-Message" from the drop down
  6. In the Event Type field, select "all types" which gives you access to all voice related events, or if you want a particular event you can select it from the drop down. ( See next section for more information on Message related events)
  7. Next, select the Delivery Configuration (Webhook url) you've already setup
  8. Create a matching criteria if you want ( See SCG Knowledge Base for more information on how to use the matching criteria)
  9. Select a Start Date and optionally an end date if you have one.
  10. Click "Create" to complete your Event subscription.

SCG-Message Service Topic Details

The SCG-Message topic is composed on various event types that can be triggered depending on the type of event status the user is looking to capture

Below are a list of supported event types in the SCG-Message topic

  • message_request_state_change : Usually invoked when the Bulk Message API is used to send messages

(Validation Type = Strict)

Name Type Mandatory Example
reason_code Text Yes "200"
company-id Integer No  
previous_state Text Yes "ACCEPTED"
message_request_id Text Yes "9W2pCL14GU3qwNJK3mtpB"
external_message_request_id Text No  
mt_price Decimal No  
external_id Text No  
reason_description Text Yes "SUCCESS"
new_state Text Yes "COMPLETED"
application_id Integer No "1864"

 

Example:

{
  "topic": "SCG-Message",
  "attempt": 1,
  "event": {
    "fld-val-list": {
      "reason_code": "200",
      "previous_state": "ACCEPTED",
      "company-id": 1672,
      "message_request_id": "9W2pCL14GU3qwNJK3mtpB",
      "new_state": "COMPLETED",
      "reason_description": "SUCCESS",
      "application_id": 1864
    },
    "evt-tp": "message_request_state_change",
    "timestamp": "2019-10-20T17:41:30.312Z"
  },
  "event-id": "sO9hXmMUTxG3chzL9vDFVA"
}
  • message_request_state_change : Usually invoked when the Direct Message API is used to send messages

(Validation Type = Strict)

 

Name Type Mandatory Example
message_id Text Yes "kFeSlKkKLb0xGjO2hk9R25"
message_request_id Text No "9W2pCL14GU3qwNJK3mtpB"
attachment_ids Text No  
mt_price Decimal No "$0.0125"
mo_price Decimal No  
previous_state Text Yes "SENT"
external_id Text No  
has_attachment Boolean No "false"
to_address Text No "+14085551212"
from_address Text No "664456"
number_type Text No  
reason_description Text Yes "SUCCESS"
application_id Integer No  
reason_code Text Yes "200"
sender_id_alias Text No "Kolanator"
sender_id_id Text No "RexWQXiD7pF7KzvepiygC7"
external_message_request_id Text No  
new_state Text Yes "DELIVERED"
company-id Integer No  
fragments_count Integer No 1

 

Example:

{
  "topic": "SCG-Message",
  "attempt": 1,
  "event": {
    "fld-val-list": {
      "previous_state": "SENT",
      "message_request_id": "9W2pCL14GU3qwNJK3mtpB",
      "message_id": "kFeSlKkKLb0xGjO2hk9R25",
      "to_address": "+14085512125",
      "has_attachment": false,
      "reason_description": "SUCCESS",
      "application_id": 1864,
      "reason_code": "200",
      "sender_id_alias": "Gladiator",
      "company-id": 1672,
      "sender_id_id": "RexWQXiD7pF7KzvepiygC7",
      "external_message_request_id": "",
      "new_state": "DELIVERED",
      "fragments_count": 1,
      "from_address": "664456",
      "mt_price": 0.0125
    },
    "evt-tp": "message_state_change",
    "timestamp": "2019-10-20T17:41:35.004Z"
  },
  "event-id": "bV58OCnrQEGqpQLvkl8y5g"
}
  • mo_received_message : This event is usually invoked when a message is received from an end-user to your Sender ID. e,g MO SMS message.

(Validation Type = Strict)

 

Name Type Mandatory Example
message_id Text Yes "MsNg=OsEwPSYSN2vLXsUFtcw_GRCS"
message_request_id Text No  
attachment_ids Text No  
has_attachment Boolean No  
mo_price Decimal No "$0.001"
to_address Text No "716219596086"
from_address Text No "+14085551212"
external_id Text No  
application_id Integer No "4334"
sender_id_alias Text No  
sender_id_id Text No "gtz9wXVkA51HSyB5wYTcP"
message_body Text Yes "Hello"
message_body_truncated Boolean No  
encrypted_event_fields Text No  
fragments_count Text No "1"
message_body_content_type Text No  
company-id Integer No "1672"
mt_price Decimal No  

 

Example:

{ 
 "topic": "SCG-Message",
  "attempt": 1,
  "event": {
    "fld-val-list": {
      "sender_id_alias": "Kolanator",
      "mo_price": 0.001,
      "company-id": 1672,
      "sender_id_id": "gtz9wXVkA51HSyB5wYTcP",
      "message_body": "Cool",
      "message_id": "MsNg=OsEwPSYSN2vLXsUFtcw_GRCS",
      "to_address": "716219596086",
      "has_attachment": false,
      "from_address": "+14085551212",
      "application_id": 4334
    },
    "evt-tp": "mo_message_received",
    "timestamp": "2019-10-27T15:59:23.091Z"
  },
  "event-id": "J_a1kSDuQgeW0rJWYWB_7w"
}

Copyright © 2023 Syniverse Technologies