Send Message v2

🚧

API Endpoint and Authentication

  • Your API endpoint varies based on where your imiconnect account is hosted. Visit Know Your API Endpoint section to know more.

  • You can use either Service Key or JSON Web Tokens (JWT) for authentication. If you use both JWT authentication and Service Key in an API request, JWT authentication takes priority, and the Service Key is ignored.

The messaging API supports batching. You can send personalized messages to a maximum of 1000 destinations at once (subject to your TPS limits). E.g., if your messaging API TPS configuration is 10 you can send messages to up to 10 destinations at once.

Prerequisites

Channel

Prerequisite

SMS

Sender ID - A Sender ID is a name or number that an SMS appears to come from (‘from address’) when you receive a message on your phone.

A sender ID can be alpha-numeric or a short-code or a long-code depending on demographical restrictions

Email

You will need to set up an Email app within imiconnect and verify your domain before you are able to send emails.

Please contact the Support team for any assistance in setting up Email app

RCS

RCS chatbot needs to be created on all operators in geography before RCS messages can be sent.

This setup takes at least 7 days after submission on the UI under the apps section of imiconnect

Messaging API v2 - Samples

{
    "appid":"<channel asset specific App ID available in Assets page>", //This is required only for Push, In-App, Messenger, WhatsApp, Twitter DMs, WeChat, and Apple Messages for Business
  "channel":"<channel name - v2 API currently supports sms, email and rcs",
    "from":"<from address for the message, for SMS this will be a senderID, for email the sender address and for all OTT channels it will be appId available on the UI>",
    "to":[
        {
            "msisdn/email":[
                "single/multiple destination objects of the same type"
            ],
            "correlationId":"<correlationId for this array of destination objects>",
            "substitutions":{
                "parameter1":"<substitutions for this array of destination objects> ",
                "parametern":"<substitutions for this array of destination objects> "
            }
        },
        // Pass multiple objects in a single destination array for bulk messaging
 
                // Pass one object in each destination array for personalized messaging     
                 {
            "msisdn/email":[
                "single/multiple destination objects of the same type"
            ],
            "correlationId":"<correlationId for this array of destination objects>",
            "substitutions":{
                "parameter1":"<substitutions for this array of destination objects> ",
                "parametern":"<substitutions for this array of destination objects> "
            }
        }
    ],
    // Global substitutions
   "substitutions":{
        "parameterx":"<global replaceable parameters, destination level parameters take precendence",

    },
    // Message scheduling
   "sendAt":"<ISO8601 date/time>",
//max 7 days from current time
   // Only 1 of these 2 can be used. If both come then it's a 400 Bad request
 "expireAt":"<ISO8601 date/time>",
 "validity":"time period in seconds",
// 1-3 message priority. 1 being the lowest
   "priority":" <priority number>",
// Channel specific message options
    "options":{
        object(smsOptions)||object(emailOptions)||Object(rcsOptions)
    },
    // Call-backs
 "callbackData":"<notify data>",
"notifyUrl":"https://notify.example.com",
"requestedReceipts":[
        "DELIVERED",
        "READ"
    ],
 // Union field message can be only one of content or template
   "content":{
    object(smsMessage)||object(emailMessage)||object(rcsMessage)
   },
    "template":{
        "id":"<unique template ID fom the UI"
    }
}
{
   "channel":"sms",
   "from":"CNNECT",
   "priority":"1",
   
   "to":[
      {
         "msisdn":[
          
            "9196zzzzzzzz"
         ]
    
       
      }
     
   ],

    "smartlinks":[
   {
     "smartlinkId": 5,
     "validity": 30
   }
   ],

   "substitutions":{
      "name":"abc",
      "value":"123"
   },
 
   "options":{
      "trackClicks":"true",
      "shortenLinks":"true",
      "domain":"https://domainname",
      "extras":{
          "dlt_templateid":"123456789"
          
          
          
      }
      
      
   },
   
 
   "callbackData":"CallBackdata",
   "notifyUrl":"https://requestinspector.com/inspect/01evrfdrr7jc662279wjskfbk6",
   
   
   "requestedReceipts": [
       "SENT",
        "DELIVERED","Clicked"
        
    ],
   "content":{
      "type":"text",
      "text":"Hi user, there is an outage in your area $(area) for the next $(value)"
}
{
    "channel":"email",
    "from":"[email protected]",
    "to":[
        {
            "email":[
                "[email protected]",
                "[email protected]"
            ],
            "correlationId":"na1b2b1i1",
            "substitutions":{
                "area":"EC1M 4BH",
                "accountNumber":"38S189"
            }
        },
        {
            "email":[
                "[email protected]"
            ],
            "correlationId":"na1b2b1i1",
            "substitutions":{
                "area":"NW10 2QD",
                "accountNumber":"SA129"
            }
        }
    ],
    "substitutions":{
        "offerName":"Big OFFER",
        "value":"123"
    },
    "cc":[
        "[email protected]"
    ],
    "bcc":[

    ],
    "callbackData":"<notify data>",
    "notifyUrl":"https://webhook.site/d50dd211-8c06-440f-ba49-36f88e5eb6e4",
    "options":{
        "trackClicks":true,
        "trackOpens":true,
        "fromName":"Brand Name"
    },
    "content":{
        "type":"html",
        "subject":"Food",
        "replyTo":"[email protected]",
        "attachments":[
            {
                "mimeType":"image/png",
                "name":"wings",
                "mediaUrl":"https://i.imgur.com/y5GjuE8.jpg"
            }
        ],
        "text":"This is a new email",
        "html":"<a no-track-connect href=\"http://example.com\">link text</a><footer><a data-mce-href='$(unsubscribe)' href='$(unsubscribe)' target='_blank' rel='noopener'><span st-unsubscribe='' style='text-decoration: none; color: #0088cc;' data-mce-style='text-decoration: none; color: #0088cc;'>unsubscribe</span></a></footer>"
    }
}
{ 
    "channel":"rcs",
    "from":"a_156887855308557980",
    "to":[
        {
            "msisdn":[
                "+916304451252"
            ],
            "correlationId":"na1b2b1i1",
            "substitutions":{
                "name":"John",
                "company":"IMI"
            }
        }
    ],
    "substitutions":{
        "company":"Mobile"
    },
    "callbackData":"abc",
    "options":{
        "smsFallback":true,
        "smsSenderId":"senderaddress",
        "text":"fallback text",
      "carrierId":"41"
    },
    "notifyUrl":"https://requestinspector.com/inspect/01dp3d028s11zeetkqbvp562st",
    "requestedReceipts":[
        "DELIVERED"
    ],
    "content":{
        "type":"standalone",
        "richCard":{
            "title":"The Card Title",
            "description":"The description",
            "orientation":"VERTICAL/HORIZONTAL",
            "thumbnailAlignment":"LEFT",
            "media":{
                "height":"SHORT/MEDIUM/TALL",
                "url":"https://bit.ly/2J5i2x0",
        "fileSize":1212 //in Bytes
            },
            "suggestions":[
                {
                    "type":"reply",
                    "displayText":"Yes",
                    "postbackData":"usr_msg_yes"
                },
                {
                    "type":"viewLocation",
                    "address":"+14165551234",
                    "displayText":"Mobile Office",
                    "latitude":43.649269,
                    "longitude":-79.378423,
                    "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
                }
            ]
        },
        "suggestions":[
            {
                "type":"reply",
                "displayText":"Yes",
                "postbackData":"usr_msg_yes"
            },
            {
                "type":"viewLocation",
                "address":"+14165551234",
                "displayText":"Mobile Office",
                "latitude":43.649269,
                "longitude":-79.378423,
                "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
            }
        ]
    }
}

Postman Collection

Try our APIs using the Postman collection here:

Run in PostmanRun in Postman.

👍

Generating the JWT Token

Connect uses a subset of the JWT fields, described here:

alg
A string used in the header, identifying the algorithm used to encode the payload. The alg value is always HS256 when exchanging messages with Business Chat.

iss
A claim that is a string identifying the principal that issued the JWT. The value is always the Service ID when exchanging messages with API V2.

iat
A claim that is a numeric date—that is, an integer—identifying the time at which the JWT was issued. The value is the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date and time, ignoring leap seconds. For more information, see the Terminology section in RFC 7519.

A Service Secret that is a Base64-encoded string. Decode the string before using the key to sign the JWT

A decoded JWT token should contain the following -

header
{
  "alg": HS256,
}
claims
{
  "iss": <Service ID>,
  "iat": <issued at unix-timestamp (in seconds)>
}

Body Parameters

Parameter

Type

Mandatory

Description

channel

enum

yes

  • sms
  • email
  • rcs

from

string

yes

  • sms - Sender ID
  • email - [email protected] (domain needs to be registered in apps)
  • rcs - app ID generated on the UI

to

JSONArray

yes

array of destination JSON objects that contain the channel specific destination and personalized substitutions for each destination object

Channel wise destinations -

  • sms - msisdn
  • email - email
  • rcs - msisdn

substitutions

JSONObject

no

a JSON object with global substitutions. If a variable exists both in personalized substitutions and global substitutions, the personalized substitution takes preference

sendAt

date/time

no

IS08601 time format for when the message has to be delivered (max 7 days)

For example,

  • 2021-06-26T13:47:18.000Z - UTC
  • 2021-06-26T13:47:18.000+05:30 - with timezone
  • 1624782447 - epoch timestamp

expireAt

date/time

no

IS08601 time format for when the message has to be expired and failed if not delivered

For example,

  • 2021-06-26T13:47:18.000Z - UTC
  • 2021-06-26T13:47:18.000+05:30 - with timezone
  • 1624782447 epoch timestamp

priority

enum

no

A value between 1-3 with 1 being the lowest priority.

API requests that contain invalid values in priority fields will be rejected.

options

JSONObject

no

a JSON object that contains additional channel specific options in API. More information under each channel below

callbackData

string

no

a string that is returned with each outbound web-hook for the message (delivery, failed etc)

notifyUrl

string

no

a HTTPS endpoint for message delivery web-hooks

requestedReceipts

JSONArray

no

a JSON array that can filter message delivery web-hooks to the notifyURL.

Can contain one or more of the following for each channel

  • sms - [submitted, delivered, undelivered, failed]
  • email - [submitted, delivered, not verified, invalid, bounced, complaint, read, failed]
  • rcs - [submitted, delivered, read, failed]

Check Outbound Webhooks for more information on receipts

content

JSONObject

yes, if template is not provided

contains the content of the message for each channel. see below for more examples

template

JSONObject

yes, if content is not provided

contains the template id for each channel that's configured on the UI

SMS Channel

smsOptions

parameter

type

description

shortenLinks

boolean

When enabled, this shortens any https links found in the body the message request

domain

string

Domain configuration for shortening the links. Needs to be configured through Support team.

trackClicks

boolean

When shortenLinks is true, you can receive CLICKED receipts on your notifyUrl if trackClicks is true. Clicked format available here

{
    "shortenLinks":true, //shortens any https links found in the body of the request
    "domain":"https://me.co.uk", //domain for the shorternedLink  must be preconfigured.Please reach out to the support team.
        "trackClicks":true //when shorten links is true, clicks can be tracked

}

smsMessage

parameter

type

mandatory

description

type

string

yes

text or unicode

text

string

yes

body of the message upto 1024 chars

{
    "type":"text or unicode",
    "text":"Hi $(name), this is a text message ${field2}" //body of the message with variables represented as $(variable)
}

Email Channel

emailOptions

parameter

type

description

trackClicks

boolean

When enabled, this tracks all links in the HTML body unless a link is tagged as no-track-connect within the anchor tags

trackOpens

boolean

When enabled, this tracks opens of the email

fromName

string

A string that will appear next to the from address in most email inboxes

{
    "trackClicks":true, //to track clicks in the email
    "trackOpens":true, //to track email opens
    "fromName":"IMI UK", //from name that appears in the email inbox
}

emailMessage

parameter

type

mandatory

description

type

string

yes

text or html

subject

string

yes

subject of the email

replyTo

string

no

reply path for the email when the customer responds

attachments

JSONArray

no

up-to 10MB of attachments

text

string

yes, when type=text
optional, when type=html

text content of the email

html

string

yes, when type=html

raw HTML for the email. Up to 350 kbps in size.

📘

Email Size Limitations

The maximum email size that you can send includes any images and attachments that are part of the email after MIME encoding. For example, if you attach a 5MB file, the attachment size in the email after MIME encoding will be ~6.85MB (about 137% of the original file size).

{
      "type":"html",
      "subject":"",
      "replyTo":"[email protected]",
      "attachments":[
         {
            "mimeType":"text/plain",
            "name":"myfile.txt",
            "mediaUrl": "https://example.com/media/123/person.png"
         },
         {
            "mimeType":"text/plain",
            "name":"myfile.txt",,
            "mediaUrl": "https://example.com/media/123/person.png"
         }
      ],
      "text":"This is a new email",
   }
{
      "type":"html",
      "subject":"",
      "replyTo":"[email protected]",
      "attachments":[
         {
            "mimeType":"text/plain",
            "name":"myfile.txt",
            "mediaUrl": "https://example.com/media/123/person.png"
         },
         {
            "mimeType":"text/plain",
            "name":"myfile.txt",
            "mediaUrl": "https://example.com/media/123/person.png"
         }
      ],
      // Both text and HTML can be sent for type=html //
      "text":"This is a new email",
      "html":"<a no-track-connect href=\"http://example.com\">link text</a>"
   }

RCS Channel

rcsOptions

parameter

type

description

smsFallback

boolean

when true, auto SMS fallback will be tried for RCS failures

smsSenderId

string

Sender ID that is already configured on your account

text

string

text message up-to 1024 chars

carrierId

string

if you already know the carrier of the end customer, you can pass this as an optional parameter.

increases the throughput of RCS outbound messages

for list of carrierIds, check here

{
    "smsFallback":true, //to enable sms fallback if user is not RCS enabled
    "smsSenderId":"senderaddress",
    "text":"fallback text",
  "carrierId":"12"
}

rcsMessage

parameter

type

mandatory

description

type

string

yes

text, media, standalone, carousel, agentEvent

text

string

yes, if type = text

up to 3072 chars

mediaContentUrl

string

yes, if type = media

a publicly accessible direct media Url ending in the attachment mimeType

richCard

JSONObject

yes, if type = standalone

a JSON object containing rich card data and suggestions

width

string

yes, if type = carousel

a parameter that indicates the width of carousel cards

cards

JSONArray

yes, if type = carousel

a JSON array containing carousel card objects and their suggestions

event

string

yes, if type = agentEvent

a typing or a read event to be sent to the customer

suggestions

JSONArray

no

a JSON array that can contain upto 10 suggestions with a message, 2 when within a carousel and 4 when within a richcard

  • reply
  • viewLocation
  • shareLocation
  • openUrl
  • calendarEvent
  • dialPhone
{
    "type": "text",
    "text": "This is the message.  Reply Yes or No.",
    "suggestions": [
        {
            "type": "reply",
            "displayText": "Yes",
            "postbackData": "usr_msg_yes"
        },
        {
            "type": "viewLocation",
            "address": "+14165551234",
            "displayText": "Mobile Office",
            "latitude": 43.649269,
            "longitude": -79.378423,
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "shareLocation",
            "displayText": "Office",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "openUrl",
            "displayText": "Mobile",
            "url": "http://www.imimobile.com",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "calendarEvent",
            "displayText": "Mobile",
            "startTime": "2017-03-14T00:00:00Z",
            "endTime": "2017-03-14T00:00:00Z",
            "meetingTitle": "http://www.imimobile.com",
            "meetingDescription": "http://www.imimobile.com",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "dialPhone",
            "displayText": "Call Us!",
            "phone": "+14163688400",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        }
    ]
}
{
    "type": "media",
    "mediaContentUrl":"https://asset.com/asset.jpg",
    "fileSize":1148279
    "suggestions": [
        {
            "type": "reply",
            "displayText": "Yes",
            "postbackData": "usr_msg_yes"
        },
        {
            "type": "viewLocation",
            "address": "+14165551234",
            "displayText": "Mobile Office",
            "latitude": 43.649269,
            "longitude": -79.378423,
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "shareLocation",
            "displayText": "Office",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "openUrl",
            "displayText": "Mobile",
            "url": "http://www.imimobile.com",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "calendarEvent",
            "displayText": "Mobile",
            "startTime": "2017-03-14T00:00:00Z",
            "endTime": "2017-03-14T00:00:00Z",
            "meetingTitle": "http://www.imimobile.com",
            "meetingDescription": "http://www.imimobile.com",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "dialPhone",
            "displayText": "Call Us!",
            "phone": "+14163688400",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        }
    ]
}
{
    "type":"standalone",
    "richCard":{
        "title":"The Card Title",
        "description":"The description",
        "orientation":"VERTICAL/HORIZONTAL",
        "thumbnailAlignment":"LEFT",
        "media":{
            "height":"SHORT/MEDIUM/TALL",
            "url":"https://bit.ly/2J5i2x0",
      "fileSize":1148279 //in Bytes
        },
        "suggestions":[
            {
                "type":"reply",
                "displayText":"Yes",
                "postbackData":"usr_msg_yes"
            },
            {
                "type":"viewLocation",
                "address":"+14165551234",
                "displayText":"Mobile Office",
                "latitude":43.649269,
                "longitude":-79.378423,
                "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
            }
        ]
    },
    "suggestions":[
        {
            "type":"reply",
            "displayText":"Yes",
            "postbackData":"usr_msg_yes"
        },
        {
            "type":"viewLocation",
            "address":"+14165551234",
            "displayText":"Mobile Office",
            "latitude":43.649269,
            "longitude":-79.378423,
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        }
    ]
}
{
    "type": "carousel",
    "suggestions": [
        {
            "type": "reply",
            "displayText": "Yes",
            "postbackData": "usr_msg_yes"
        },
        {
            "type": "viewLocation",
            "address": "+14165551234",
            "displayText": "Mobile Office",
            "latitude": 43.649269,
            "longitude": -79.378423,
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "shareLocation",
            "displayText": "Office",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "openUrl",
            "displayText": "Mobile",
            "url": "http://www.imimobile.com",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "calendarEvent",
            "displayText": "Mobile",
            "startTime": "2017-03-14T00:00:00Z",
            "endTime": "2017-03-14T00:00:00Z",
            "meetingTitle": "http://www.imimobile.com",
            "meetingDescription": "http://www.imimobile.com",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        },
        {
            "type": "dialPhone",
            "displayText": "Call Us!",
            "phone": "+14163688400",
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        }
    ],
    "width": "SMALL/MEDIUM",
    "cards": [
    {
        "title": "The first card",
        "description": "The first card description",
        "media": {
             "height": "SHORT/MEDIUM/TALL",
             "url": "https://bit.ly/2J5i2x0",
             "fileSize":1148279
        },
 "suggestions": [
        {
            "type": "reply",
            "displayText": "Yes",
            "postbackData": "usr_msg_yes"
        },
        {
            "type": "viewLocation",
            "address": "+14165551234",
            "displayText": "Mobile Office",
            "latitude": 43.649269,
            "longitude": -79.378423,
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        }
    ],
    },
    {
        "title": "The second card",
        "description": "The second card description",
        "media": {
            "height": "SHORT/MEDIUM/TALL",
            "url": "https://bit.ly/2P5Q9dK",
            "fileSize":1148279
        },
 "suggestions": [
        {
            "type": "reply",
            "displayText": "Yes",
            "postbackData": "usr_msg_yes"
        },
        {
            "type": "viewLocation",
            "address": "+14165551234",
            "displayText": "Mobile Office",
            "latitude": 43.649269,
            "longitude": -79.378423,
            "postbackData":"e460dd65-e69b-4f86-a5af-458683248f2d_url_google"
        }
    ]
    } ]
}
{
    "type": "agentEvent",
    "event": "IS_TYPING"
}
{
    "type": "agentEvent",
    "event": "READ",
    "messageId": "3682cb0f-5dae-42fe-9a75-2aea271efeff
}

📘

Suggestions

reply
Suggested replies help your chatbot guide users through conversations by providing responses that the chatbot knows how to react to. Your agent sends replies in suggestion chip lists or rich cards.

viewLocation
The View location action displays a location in the user's default map app. You can specify the location either by latitude and longitude or with a query based on the user's current location. You can also set a custom label for the pin that displays in the map app.

shareLocation
The Share location action lets the user send a location to your chatbot.

openUrl
The Open URL action opens the user's web browser to the specified URL. If an app is registered as a default handler for the URL, the app opens instead, and the icon for the action is the app's icon.

calendarEvent
The Create calendar event action opens the user's calendar app and begins to create a new event with the specified information.

dialPhone
The Dial action guides the user to dial a phone number that your chatbot specifies.

Language
Authentication
Header