post https://api.imiconnect.io/resources/v1/messaging
Text Message
{
"preview_url":true,
"type":"text",
"text":{
"body":"This is for sample test message"
}
}
| Parameter | Mandatory | Description |
|---|---|---|
| text | Yes | Contains the body field. |
| type | Yes | When the channel type is text |
| preview_url | No | Options: false (default), true Specifying preview_url in the request is optional when not including a URL in your message. To include a URL preview, set preview_url to true in the message body and make sure the URL begins with http:// or https://. |
The text object
| Parameter | Mandatory | Description |
|---|---|---|
| body | Yes | The text of the text message, which can contain URLs and formatting |
Contacts Message
{
"type": "contacts",
"contacts": [
{
"addresses": [
{
"city": "Menlo Park",
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "1 Hacker Way",
"type": "HOME",
"zip": "94025"
},
{
"city": "Menlo Park",
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "200 Jefferson Dr",
"type": "WORK",
"zip": "94025"
}
],
"birthday": "2012-08-18",
"emails": [
{
"email": "[email protected]",
"type": "WORK"
},
{
"email": "[email protected]",
"type": "WORK"
}
],
"name": {
"first_name": "John",
"formatted_name": "John Smith",
"last_name": "Smith"
},
"org": {
"company": "WhatsApp",
"department": "Design",
"title": "Manager"
},
"phones": [
{
"phone": "+1 (940) 555-1234",
"type": "HOME"
},
{
"phone": "+1 (650) 555-1234",
"type": "WORK",
"wa_id": "16505551234"
}
],
"urls": [
{
"url": "https://www.facebook.com",
"type": "WORK"
}
]
}
]
}
Parameters
| Object | Parameter | Description | Mandatory |
|---|---|---|---|
| addresses | Full contact address(es) | No | |
| street | Street number and name | No | |
| city | City name | No | |
| state | State abbreviation | No | |
| zip | ZIP code | No | |
| country | Full country name | No | |
| country_code | Two-letter country abbreviation | ||
| type | Standard Values: HOME, WORK | No | |
| birthday | YYYY-MM-DD formatted string | No | |
| emails | Contact email address(es) | No | |
| Email address | No | ||
| type | Standard Values: HOME, WORK | No | |
| name | Full contact name | No | |
| formatted_name | Full name as it normally appears | Yes | |
| first_name | First name | Optional* | |
| last_name | Last name | Optional* | |
| middle_name | Middle name | Optional* | |
| suffix | Name suffix | Optional* | |
| prefix | Name prefix | Optional* | |
| org | Contact organization information | No | |
| company | Name of the contact's company | No | |
| department | Name of the contact's department | No | |
| title | Contact's business title | No | |
| phones | Contact phone number(s) | No | |
| phone | Automatically populated with the wa_id value as a formatted phone number. | No | |
| type | Standard Values: CELL, MAIN, IPHONE, HOME, WORK | No | |
| wa_id | WhatsApp ID | No | |
| urls | Contact URL(s) | No | |
| url | URL | No | |
| type | Standard Values: HOME, WORK | No |
- At least one of the optional parameters needs to be included along with the formatted_name parameter.
Location Message
{
"type": "location",
"location": {
"longitude": -122.425332,
"latitude": 37.758056,
"name": "Facebook HQ",
"address": "1 Hacker Way, Menlo Park, CA 94025"
}
}
Parameters
| Parameter | Description | Mandatory |
|---|---|---|
| longitude | Longitude of the location | Yes |
| latitude | Latitude of the location | Yes |
| name | Name of the location | No |
| address | Address of the location. Only displayed if name is present. | No |
Media Message
| Parameter | Mandatory | Description | |
|---|---|---|---|
| type | Yes, when type is image, audio, or document. | image, audio, document, hsm | |
| audio | Yes, when "type": "audio". | The media object containing audio. Supported audio formats are AAC, M4A, AMR, MP3, OGG, OPUS | |
| document | Yes, when "type": "document". | The media object containing a document. Supported document formats are PDF, DOC(X), PPT(X), The media object containing a videoXLS(X) | |
| image | Yes, when "type": "image". | The media object containing an image. Supported image formats are JPG, JPEG, PNG | |
| video | Yes, when "type": "video" | The media object containing a video | |
| sticker | Yes, when "type":"sticker" | The media object containing a sticker |
The audio, document, image, video and sticker objects
| Parameter | Mandatory | Description |
|---|---|---|
| caption | No | Describes the specified image, video, or document media. Do not use with audio or sticker media. |
| url | yes | Direct URL pointing to the media file. The URL should end with specified file-format. You can use our Media manager under Tools to upload a file and get a public URL. |
| mimeType | yes | Supported mimeTpes |
{
"type":"audio" ,
"audio":{
"url":"your-media-url",
"mimeType":"audio/m4a"
}
}
{
"type":"document",
"document":{
"url":"your-media-url",
"caption":"your-document-caption",
"mimeType":"application/pdf"
}
{
"type":"image",
"image":{
"url":"your-media-url",
"caption":"your-image-caption",
"mimeType":"image/png"
}
{
"type":"video",
"video": {
"url": "http://techslides.com/demos/sample-videos/small.mp4",
"caption": "your-video-caption",
"mimeType": "video/MP4"
}
{
"type":"sticker" ,
"sticker":{
"url":"your-media-url",
"mimeType":"image/webp"
}
}
HSMs - Text based notification message
| Parameter | Mandatory | Description | |
|---|---|---|---|
| type | Yes (for Message Templates) | The type of message being sent | |
| hsm | Yes (for Message Templates) | The containing element for the message content — Indicates that the message is highly structured. Parameters contained within provide the structure. |
HSM API usage
HSM type APIs can only be used to send text-based notification messages. If you intend to send notification messages with media refer to the Template type API.
The hsm object
| Parameter | Mandatory | Description |
|---|---|---|
| namespace | Yes | The namespace that will be used |
| element_name | Yes | The element name that indicates which template to use within the namespace |
| language | Yes | Allows for the specification of a deterministic or fallback language See the Language section for more information. |
| localizable_params | Yes | This field is an array of values to apply to variables in the template See the Localizable Parameters section for more information. |
language
| Parameter | Mandatory | Description |
|---|---|---|
| policy | Yes | Options: fallback (deprecated), deterministic The language policy the message should follow |
| code | Yes | The code of the language or locale to use — Accepts both language and language_locale formats (e.g., en and en_US). |
The language parameter sets the language policy for a Message Template; you can set it to either fallback or deterministic.
There are two policies that you can specify when sending a Message Template: deterministic and fallback.
- deterministic — Deliver the Message Template in exactly the language and locale asked for.
- fallback (Deprecated) — Deliver the Message Template in the language that matches the user's language/locale setting on the device. If one can't be found, deliver using the specified fallback language.
The only real difference is that with fallback, we try to locate the language pack using the device's language/locale setting first.
WhatsApp Language Policy Change
Please note that the fallback language policy has been deprecated and the deterministic language policy is now the default policy. Do not use 'fallback' language policy while sending HSMs as it may lead to message delivery failures.
- Localizable Parameters
When sending a Message Template, the hsm object is required. To define Message Templates, you specify a namespace and an element_name pair that identify a template. Templates have parameters that will be dynamically incorporated into the message. For the example used in this document, the Message Template looks like this:
| Parameters | Type | Mandatory | Description |
|---|---|---|---|
| default | String | Yes | Default text if localization fails |
| currency | currency object | No | If the currency object is used, it contains required parameters currency_code and amount_1000. |
| date_time | date_time object | No | If the date_time object is used, further definition of the date and time is required. |
Using WhatsApp Media templates within Messaging API v1
If you have set-up a WhatsApp Media template from within Tools ->Templates section, you need to use Media Template section (refer the section after HSM). HSM object cannot be used to reference WhatsApp Media Templates created from Tools ->Templates section within IMIconnect platform.
{
"type":"hsm",
"hsm":{
"namespace":"9470e2ab_0d74_e7b9_e70e_93005717e59f",
"element_name":"hsm_hpalt546",
"language":{
"code":"en_gb",
"policy":"deterministic"
},
"localizable_params":[
{
"default":"just a string"
},
{
"default":"$100.99",
"currency":{
"currency_code":"USD",
"amount_1000":100990
}
},
{
"default":"February 25, 1977",
"date_time":{
"component":{
"day_of_week":5,
"day_of_month":25,
"year":1977,
"month":2,
"hour":15,
"minute":33
}
}
},
{
"default":"January 26, 2017",
"date_time":{
"unix_epoch":{
"timestamp":1485470276
}
}
}
]
}
}
Template
The following is a sample API structure. The API structure is dynamic and varies based on the parameters defined in the template at the time of template creation.
Template API usage
Please note: The template should be register and approved from Tools -> Templates section within IMIconnect platform, before it can be used to send notification messages.
{
"appid": "a_157967534853754560",
"deliverychannel": "whatsapp",
"message": {
"template": "513972242591830",
"parameters": {
"movie": "joker",
"venue": "hyderabad",
"seat1": "balcony",
"seat2": "first class",
"image": {
"link": "http://mattfarmer.net/projects/thickbox/images/plant4.jpg",
"filename": "image.jpg"
},
"time": {
"type": "date_time",
"fallback_value": "Feb 20th, 2020 8:45pm",
"timestamp": "1582231500"
},
"purchase_value": {
"type": "currency",
"currency_code": "USD",
"amount_1000": "150000",
"fallback_value": "EUR 300"
}
}
},
"destination": [
{
"waid": [
"9177xxxxxxxx"
]
}
]
}
| Parameter | Mandatory | Description |
|---|---|---|
| appid | Yes | Refers to WhatsApp asset id. You can obtain this from the Apps page on the platform. |
| template | Yes | Refers to template id. You can obtain this from Tools > Templates page on the platform. |
| parameters | Yes | The block that contains the parameters for text message |
| >param1 | Yes | First text parameter of the text message. Use the exact name that you have used while defining the template. In the above sample code, movie is the name of the parameter. |
| >param2 | Yes | Second text parameter of the text message. Use the exact name that you have used while defining the template. In the above sample code, venue is the name of the parameter. |
| >param3 | Yes | Third text parameter of the text message. Use the exact name that you have used while defining the template. In the above sample code, seat1 is the name of the parameter. |
| >param4 | Yes | Fourth text parameter of the text message. Use the exact name that you have used while defining the template. In the above sample code, seat2 is the name of the parameter. |
| image | Yes | The block that contains the parameters for an image |
| >link | Yes | The media URL of the image |
| >filename | No | The name of the image |
| time | Yes | The block that contains the parameters for date-time |
| >type | Yes | Parameter that indicates the type as "date-time" |
| >fallback_value | Yes | The fallback value that appears to the customer when the localization fails |
| >timestamp | Yes | UNIX epoch timestamp that is used to calculate the localized date and time. Go to epoch convertor for timestamp conversion. |
| purchase_value | Yes | The block that contains the parameters for currency |
| >type | Yes | Parameter that indicates the type as "currency" |
| >currency_code | Yes | The currency code like USD, EUR, INR, etc |
| >amount_1000 | Yes | The actual amount multiplied by 1000 |
| >fallback_value | Yes | The fallback value that appears to the customer when the localization fails |
| destination | Yes | The mobile number on which the WhatsApp message will be sent |