OMNI channel: Email example

The following simple methods will allow you to send messages and retrieve message logs using Email and SMS communication channels.

Why OMNI?

Consider the following scenario: a travel agency has a large number of customers that wish to receive SMS message notifications when their itinerary changes. The flight gets delayed or canceled and different booking reservations are confirmed.

While an SMS is a very convenient way to get notified, this channel might not be all that reliable when your customers are traveling all around the world. People sometimes switch their phones off because of roaming charges, or purchase local SIM cards so they can have local network prices and data packages. And finally, spending time on the road means they can run out of battery life more easily.

This is not the only scenario in which an SMS message is not the most efficient option for reaching your customers so a backup option should be introduced. While most customers can still be reached over SMS, other communication channels like email could fill in the gaps.

Solution

This is where our Omni solution fits in perfectly. We can set it up in a way that all SMS messages that don’t get delivered in a given time frame to a customer’s device fall back on email which will then be sent instead and wait for the customer safely in their inbox. The fallback logic happens automatically so the travel agency would still send only one message.

Email setup

Learn more about email and its initial account setup: Email introduction

Here is what we are going to go over in this tutorial:

  1. Creating an Omni scenario in which we will define the order of communication channels and sender information.
  2. We will use this scenario to deliver an SMS message first. If the SMS is not delivered within 3 minutes, we will send the message over email.
  3. In the end, we will acquire message logs and examine how the message was delivered.

Step 1: Creating an Omni scenario

The first step is to create an Omni scenario. In the Omni scenario configuration you need to define the steps which will be sequentially executed. The key parameters are channel and from, respectively identifying the communication channels and senders for each communication channel.

POST /omni/1/scenarios HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
  "name": "SMS with e-mail fallback",
  "flow": [
    {
      "from": "Travel agency",
      "channel": "SMS"
    },
    {
      "from": "info@travelagency.com",
      "channel": "EMAIL"
    }
  ],
  "default": false
}	
  

Response format

If successful, the response header HTTP status code will be 200 OK and the scenario will be created, as shown in the example below.

If you try to create the scenario without authorization, you will receive the 401 Unauthorized error.

{
  "key": "AD9E01A5DC7BEE2C2B828D208182A611",
  "name":"SMS with e-mail fallback",
  "flow": [
    {
      "from": "Travel agency",
      "channel": "SMS"
    },
    {
      "from": "info@travelagency.com",
      "channel": "EMAIL"
    }    
  ],
  "default": false
}	
  

The keyparameter needs to be stored as it will be used when sending the message. In case you missed it in the response, it can be acquired again by calling the Scenario:// Get method

Step 2: Omni message sending

Once you’ve created an Omni scenario (identified by the key parameter) as described in the previous chapter, you are ready to send your Omni messages through defined SMS and Email communication channels. Firstly, the SMS message will be sent to the defined phoneNumber. If for some reason the message is not delivered, the message will then be sent to email as defined in the previously created scenario.

The parameters that should be set are the scenario key, phoneNumber, emailAddress and specific text for each communication channels, as shown below.

To make this example more interesting, let’s say that instead of a single traveler, the travel agency needs to send messages to a happy couple (John and Jane Smith) on their honeymoon.

POST /omni/1/advanced HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{ 
  "scenarioKey": "AD9E01A5DC7BEE2C2B828D208182A611",
  "destinations":[ 
    { 
      "to": {
        "phoneNumber": "385974241491",
        "emailAddress": "john.smith@gmail.com"
      }
    },
    { 
      "to": {
        "phoneNumber": "385972135566111111111",
        "emailAddress": "jane.smith@gmail.com"
      }
    }
  ],
  "sms": {
    "text": "Hello, we are happy to confirm your reservation for the safari trip.",
    "validityPeriod":3
  },
  "email": {
    "subject": "Reservation confirmed!",
    "text": "Hello, we are happy to confirm your reservation for the safari trip."
   } 
}	
  

In this example we can see that the message can be sent to one or more recipients listed in destinations collection. validityPeriod is expressed in minutes. If the message is not delivered in 3 minutes, an email will be sent as a backup option.

Response format

If the request was successful, the response header HTTP status code will be 200 OK and the message will be sent.

If you try to send the message without authorization, you will receive the 401 Unauthorized error.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "bulkId": "b608b611-0fd4-4594-9dea-39656caae30d",
  "messages": [
    {
      "to": {
        "phoneNumber": "385974241491",
        "emailAddress": "john.smith@gmail.com"
      },
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 7,
        "name": "PENDING_ENROUTE",
        "description": "Message sent to next instance"
      },
      "messageId": "05396f95-856d-47e8-bfe7-8ecaff9caa1f"
    },
    {
      "to": {
        "phoneNumber": "385972135566111111111",
        "emailAddress": "jane.smith@gmail.com"
      },
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 7,
        "name": "PENDING_ENROUTE",
        "description": "Message sent to next instance"
      },
      "messageId": "055d6674-096d-4c5e-b0d9-8285f0fd1b55"
    }
  ]
}	
  

Note

Note that the response does not provide information on if and how the message was delivered. It merely states that the message has been accepted by our server and will be processed according to the created Omni scenario.

Detailed information about delivery will be available in the message log. The easiest way to get the message log for the request is to save the bulkId value from the response which can later be used to easily filter out the logs.

Besides single bulkId, each message has its own unique messageId. Message ID can be used to identify failover messages when examining logs.

Step 3: Getting message logs

Message logs can be accessed without any filters but such a query could potentially return logs of all messages sent in the last 48 hours. By introducing bulkId as the filter parameter we can get logs for this specific request.

GET /omni/1/logs?bulkid=b608b611-0fd4-4594-9dea-39656caae30d HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json	
  

Here is the returned response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "bulkId": "b608b611-0fd4-4594-9dea-39656caae30d",
      "messageId": "055d6674-096d-4c5e-b0d9-8285f0fd1b55",
      "to": "jane.smith@gmail.com",
      "from": "info@travelagency.com",
      "text": "Hello, we are happy to confirm your reservation for the safari trip.",
      "sentAt": "2016-09-29T14:58:32.117+0000",
      "doneAt": "2016-09-29T14:58:32.747+0000",
      "messageCount": 1,
      "price": {
        "pricePerMessage": 0,
        "currency": "EUR"
      },
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      },
      "channel": "EMAIL"
    },
    {
      "bulkId": "b608b611-0fd4-4594-9dea-39656caae30d",
      "messageId": "055d6674-096d-4c5e-b0d9-8285f0fd1b55",
      "to": "385972135566111111111",
      "from": "Travel agency",
      "text": "Hello, we are happy to confirm your reservation for the safari trip.",
      "sentAt": "2016-09-29T14:58:32.070+0000",
      "doneAt": "2016-09-29T14:58:32.073+0000",
      "messageCount": 1,
      "mccMnc": "21910",
      "price": {
        "pricePerMessage": 0,
        "currency": "EUR"
      },
      "status": {
        "groupId": 5,
        "groupName": "REJECTED",
        "id": 52,
        "name": "REJECTED_DESTINATION",
        "description": "Invalid destination address.",
        "action": "Check to parameter."
      },
      "channel": "SMS"
    },
    {
      "bulkId": "b608b611-0fd4-4594-9dea-39656caae30d",
      "messageId": "05396f95-856d-47e8-bfe7-8ecaff9caa1f",
      "to": "385974241491",
      "from": "Travel agency",
      "text": "Hello, we are happy to confirm your reservation for the safari trip.",
      "sentAt": "2016-09-29T14:58:32.013+0000",
      "doneAt": "2016-09-29T14:58:32.697+0000",
      "messageCount": 1,
      "mccMnc": "21901",
      "price": {
        "pricePerMessage": 0,
        "currency": "EUR"
      },
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      },
      "channel": "SMS"
    }
  ]
}	
  

In our case, three returned log records have the same bulk ID. Two out of three messages have the same messageId because, as you can see, Jane Smith supplied an invalid phone number (too many digits) so an SMS could not be delivered (see message status and channel). This is why we have an additional message log with the same messageId confirming that the email, as a secondary delivery method, was successfully delivered. John had no problems receiving the SMS message on his phone, as we can see in the last recorded log.