OMNI channel: WhatsApp example

Find out about the simple methods which will allow you to send messages and retrieve message reports using the WhatsApp and SMS communication channels.

In the following examples, we’ll show you how to configure a WhatsApp-SMS failover scenario, send your first messages and retrieve message reports.

The messages will firstly be sent over the WhatsApp communication channel. If the messages are rejected on WhatsApp (for example, the user doesn’t have WhatsApp installed), the messages will be sent using the SMS communication channel.

There are three easy steps to follow:

1. Create OMNI scenario

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

Prerequisites

To be able to send WhatsApp messages using the Infobip platform you need to configure the WhatsApp service. Please contact us for service activation and configuration.

For WhatsApp sender (“channel”: “WHATSAPP” flow) you should use the WhatsApp sender provided during the activation process.

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

{
  "name":"My WHATSAPP-SMS scenario",
  "flow": [
    {
      "from": "WhatsAppSender",
      "channel": "WHATSAPP"
    },
    {
      "from": "InfoSMS",
      "channel": "SMS"
    }    
  ],
  "default": true
}	
  

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 a 401 Unauthorized error.

{
  "key": "CC9F01A5DC7BEE2C2B829D203482A654",
  "name":"My WHATSAPP-SMS scenario",
  "flow": [
    {
      "from": "WhatsAppSender",
      "channel": "WHATSAPP"
    },
    {
      "from": "InfoSMS",
      "channel": "SMS"
    }    
  ],
  "default": true
}	
  

The key parameter needs to be stored as it will be used when sending the message.

Info

More information about creating an OMNI scenario can be found on the following page: Scenario:// Create.

2. Send OMNI message

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 WhatsApp and SMS communication channels. First, the WhatsApp message will be sent to the defined phoneNumber. If for some reason, the message is rejected on the WhatsApp application or the end user doesn’t have the WhatsApp application installed, the message will be sent using the SMS communication channel.

For sending OMNI messages, you can use the advanced API method. Detailed descriptions of the advanced API method can be found here: OMNI:// Send an advanced message.

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

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

{
	"scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
	"destinations": [{
		"to": {
			"phoneNumber": "41793026727"
		}
	}],
	"whatsApp": {
		"text": "This WhatsApp message will be delivered to WhatsApp application on the user device."
	},
	"sms": {
		"text": "This is the SMS failover message"
	}
}	
  

WhatsApp sessions

To send any messages other than template message, user needs ti initiate session by responding to template message. Session is established for 24 hours. Only template messages can be sent without establishing session.

Response format

If 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 a 401 Unauthorized error.

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

{
	"messages": [{
		"to": {
			"phoneNumber": "41793026731"
		},
		"status": {
			"groupId": 1,
			"groupName": "PENDING",
			"id": 7,
			"name": "PENDING_ENROUTE",
			"description": "Message sent to next instance"
		},
		"messageId": "50c24400-124f-4678-9f4b-309e994a4deb"
	}]
}	
  

3. Get Delivery Reports

Once you’ve successfully sent your message using the advanced API method you can check the status of sent messages using the OMNI reports method.

The simplest way is to use the method without any query parameters. In that case, the response will contain all messages sent to a specific account.

GET /omni/1/reports HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json	
  

The response will contain all messages, rejected and delivered, as shown in the example below.

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

{  
   "results":[  
      {  
         "messageId":"1215f543ab19-345f-adbd-12ad31451ed25f35",
         "to":"41793026731",
         "messageCount": 1,
         "sentAt":"2016-02-23T17:41:11.833+0100",
         "doneAt":"2016-02-23T17:41:11.843+0100",
         "mccMnc":"22801",
         "price":{  
            "pricePerMessage":0.0104,
            "currency":"EUR"
         },
         "status":{  
            "groupId":2,
            "groupName":"UNDELIVERABLE",
            "id":9,
            "name":"UNDELIVERABLE_NOT_DELIVERED",
            "description":"Message sent not delivered"
         },
         "error":{  
            "groupId":1,
            "groupName":"HANDSET_ERRORS",
            "id":6,
            "name":"EC_ABSENT_SUBSCRIBER_SM",
            "description":"Absent Subscriber",
            "permanent":false
         },
        "channel": "WHATSAPP"
      },
      {  
         "messageId":"2315d543441c-335f-1d3d-142d31451ed25f35",
         "to":"41793026731",
         "sentAt":"2016-06-23T17:40:31.773+0100",
         "doneAt":"2016-06-23T17:40:31.787+0100",
         "messageCount":1,
         "mccMnc":"22801",
         "price":{  
            "pricePerMessage":0.01,
            "currency":"EUR"
         },
         "status":{  
            "groupId":3,
            "groupName":"DELIVERED",
            "id":5,
            "name":"DELIVERED_TO_HANDSET",
            "description":"Message delivered to handset"
         },
         "error":{  
            "groupId":0,
            "groupName":"OK",
            "id":0,
            "name":"NO_ERROR",
            "description":"No Error",
            "permanent":false
         },
        "channel": "SMS"
      }
   ]
}	
  

4. Receive incoming WhatsApp messages

In order to start receiving messages, you should set up an MO configuration and an HTTP forward action, as described in Number configuration.

Text Incoming message

{
	"results": [{
		"from": "385919998888",
		"to": "1234",
		"integrationType": "WHATSAPP",
		"receivedAt": "2018-09-10T11:57:19.782+0000",
		"messageId": "ABEGOFkWA5EBAgo6B82cNiWIAMKC",
		"pairedMessageId": null,
		"callbackData": null,
		"message": {
			"type": "TEXT",
			"text": "Message Text."
		},
		"price": {
			"pricePerMessage": 0.000000,
			"currency": "HRK"
		}
	}],
	"messageCount": 1,
	"pendingMessageCount": 0
}	
  

Image Incoming Message

{
	"results": [{
		"from": "385919998888",
		"to": "1234",
		"integrationType": "WHATSAPP",
		"receivedAt": "2018-09-10T11:27:17.980+0000",
		"messageId": "ABEGOFkWA5EBAgo6B82cNiWIAMKC",
		"pairedMessageId": null,
		"callbackData": null,
		"message": {
			"type": "IMAGE",
			"caption": "Image Caption",
			"url": "https://api.infobip.com/whatsapp/1/senders/447796344125/media/f1b96d31-9ab9-4513-808b-50ab37360fbe"
		},
		"price": {
			"pricePerMessage": 0.000000,
			"currency": "HRK"
		}
	}],
	"messageCount": 1,
	"pendingMessageCount": 0
}	
  

Document Incoming message

{
	"results": [{
		"from": "385919998888",
		"to": "1234",
		"integrationType": "WHATSAPP",
		"receivedAt": "2018-09-10T12:10:18.379+0000",
		"messageId": "ABEGOFkWA5EBAgo6B82cNiWIAMKC",
		"pairedMessageId": null,
		"callbackData": null,
		"message": {
			"type": "DOCUMENT",
			"caption": "Document caption",
			"url": "https://api.infobip.com/whatsapp/1/senders/447796344125/media/c256e11d-a7e9-4dbb-aa9c-2a6028ddf7e8"
		},
		"price": {
			"pricePerMessage": 0.000000,
			"currency": "HRK"
		}
	}],
	"messageCount": 1,
	"pendingMessageCount": 0
}	
  

Location Incoming Message

{
	"results": [{
		"from": "385919998888",
		"to": "1234",
		"integrationType": "WHATSAPP",
		"receivedAt": "2018-09-10T12:13:53.864+0000",
		"messageId": "ABEGOFkWA5EBAgo6B82cNiWIAMKC",
		"pairedMessageId": null,
		"callbackData": null,
		"message": {
			"type": "LOCATION",
			"longitude": 15.9459228515625,
			"latitude": 45.793365478515625
		},
		"price": {
			"pricePerMessage": 0.000000,
			"currency": "HRK"
		}
	}],
	"messageCount": 1,
	"pendingMessageCount": 1
}	
  

Additional Examples

Send WhatsApp template message

Template registration

For sending template messages you will need to provide template details according to which message will be send. For template registration contact us. Registration process can take more than one day.

If you would like to send WhatsApp template messages, please check the example provided below.

Parameter Type Description

templateName

string Template name

templateNamespace

string Template namespace

templateData

array of strings Template parameters values ordered as registerd in template
language string The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US).
policy string

The language policy the message should follow - deterministic or fallback.

deterministic — Deliver the Message Template in exactly the language and locale asked for.
fallback — Deliver the Message Template in the language that matches user's language/locale setting on device. If one can't be found, deliver using the specified fallback language.

This field is optional and defaults to deterministic.

WhatsApp template message

When sending WhatsApp template message, templateName, templateNamespace, templateData and language are mandatory fields!

Info

Default validity period for SMS messages is 48 hours.

WhatsApp template message request example:

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

{
	"scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
	"destinations": [{
		"to": {
			"phoneNumber": "41793026727"
		}
	}],
	"whatsApp": {
		"templateName": "template_name",
		"templateNamespace": "whatsapp:hsm:templatenamespace",
		"templateData": ["1", "12"],
		"language": "en_US"
	},
	"sms": {
		"text": "This text will be received via SMS if WhatsApp message is not delivered.",
		"validityPeriod": 1
	}
}	
  

Send WhatsApp Image message

If you would like to send WhatsApp messages containing text and image, please check the example provided below. The example also shows how to configure the custom validity period for each communication channel.

Parameter Type Description
text string Text of the message that will be sent. Max 3000 characters.
imageUrl string URL of the image sent in the WhatsApp message. Max 500 characters.

WhatsApp Image message

When sending WhatsApp image message, imageUrl is mandatory!

Image WhatsApp message request example:

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

{
	"scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
	"destinations": [{
		"to": {
			"phoneNumber": "41793026727"
		}
	}],
	"whatsApp": {
		"text": "Get your message across!",
		"imageUrl": "http://www.infobip.com/infobip-logo.png"
	},
	"sms": {
		"text": "This text will be received via SMS if WhatsApp message is not delivered.",
		"validityPeriod": 1
	}
}	
  

Send WhatsApp Audio message

If you would like to send WhatsApp messages containing audio file, please check the example provided below.

Parameter Type Description
audioUrl string URL of the audio file sent in the WhatsApp message. Max 500 characters. 

WhatsApp Audio message

When sending WhatsApp audio message, audioUrl is mandatory!

Audio WhatsApp message request example:

POST /omni/1/advanced HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
	"scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
	"destinations": [{
		"to": {
			"phoneNumber": "41793026727"
		}
	}],
	"whatsApp": {
		"audioUrl": "https://www.audioUrl.com"
	},
	"sms": {
		"text": "This text will be received if WhatsApp communication channel message is not delivered."
	}
}	
  

Send WhatsApp Document message

If you would like to send WhatsApp messages containing document file, please check the example provided below.

Parameter Type Description
text string Text of the message that will be sent. Max 240 characters.
fileUrl string URL of the file sent in the WhatsApp message. Max 500 characters.

WhatsApp Document message

When sending WhatsApp document message, fileUrl is mandatory!

Document WhatsApp message request example:

POST /omni/1/advanced HTTP/1.1
Host: {base_url}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
	"scenarioKey": "CC9F01A5DC7BEE2C2B829D203482A654",
	"destinations": [{
		"to": {
			"phoneNumber": "41793026727"
		}
	}],
	"whatsApp": {
		"text": "File caption",
		"fileUrl": "https://www.documentUrl.com"
	},
	"sms": {
		"text": "This text will be received if WhatsApp communication channel message is not delivered."
	}
}