Whatsapp For Business API

Whatsapp For Business API

PARAMETERS

Name Description type Required
channels This block contains information related messaging channel N/A Yes
name Name of Messaging Channel. Ex: whatsapp string Yes
from Sender or From Number number Yes
recipient This block contains contacts information related to channel N/A Yes
group_id Segment id which contain list of phone numbers string or array Yes if to param not present
to Receiver mobile numbers : text array Yes, if group_id not present

Note : The recipient block inside channel is related to particular communication channel and it is optional. The outside recipient channel contain common recipients for every channel.

{
	"channels": [{
		"name": "whatsapp",
		"from": "91901912xxxx",
        "meta" : {
            "foreign_id":"your-custom-id"
        }
	}]
	"recipient": {
		"group_id": "{segment_id}",
		"to": ["91XXXXXX", "91XXXXXX"]
	}
}

Example Response

{
  "status": "OK",
  "message": "Message Queued successfully",
  "data": [
    {
      "id": "a418d672-9781-4d97-b517-a56f7d95ad8a",
      "channel": "whatsapp",
      "from": "919019120xxx",
      "to": "9190199xxxxx",
      "credits": 1,
      "created_at": "2021-06-18T14:48:06.886358Z",
      "status": "queued",
      "foreign_id": "your-message-id"
    }
  ]
}

It will support only POST requests.

API Endpoint

https://eu.cpaas.bics.com/api/v2/

Note: Few elements in the endpoint may change from service to service.

{endpoint}whatsapp/message/send

PARAMETERS

Name Description Limits Required
to Destination mobile number with country code NA Yes
payload Message Payload section N/A Yes
text Message Content you want to send Max 4096 Characters Yes

Example Request With Text Message

cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "channels": [
        {
            "name": "whatsapp",
            "from": "{from}"
        }
    ],
    "recipient": {
        "to": [
            "{receiver}"
        ]
    },
    "message": {
        "type": "text",
        "payload": {
            "text": "This is a simple text message from whatsapp channel"
        }
    }
}'
{endpoint}whatsapp/message/send

PARAMETERS

Name Description Limits Required
url Public url of the image file. Either HTTP/HTTPS link. 5 MB Yes
type image/jpg, image/jpeg and image/png YES YES
caption some text for image caption N/A No
filename Media file name N/A No
pixels vertically crops images with the 1:91:1 aspect ratio: 800×418 pixels. To communicate effectively, design the image such that the crux information is at the center of the image. YES YES

Example Request With Image Message

cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "channels": [
        {
            "name": "whatsapp",
            "from": "{from}"
        }
    ],
    "recipient": {
        "to": [
            "{receiver}"
        ]
    },
    "message": {
        "type": "image",
        "payload": {
            "url": "https://picsum.photos/id/237/200/300",
            "caption": "some caption for document",
            "filename": "Sample Image file"
        }
    }
}'

We can send Document which is having valid MIME-type as attachment using below API. So anything not image, audio or video will be transmitted as document message.

{endpoint}whatsapp/message/send

PARAMETERS

Name Description Limits Required
url Public url of the document file. Either HTTP or HTTPS link. Max File size 100MB Yes
type Any valid MIME-type N/A No
caption some text for document caption N/A No
filename Media file name N/A No

Example Request With Document Message

cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "channels": [
        {
            "name": "whatsapp",
            "from": "{from}"
        }
    ],
    "recipient": {
        "to": [
            "{receiver}"
        ]
    },
    "message": {
        "type": "document",
        "payload": {
            "url": "http://www.africau.edu/images/default/sample.pdf",
            "caption": "some caption for document",
            "filename": "Sample PDF file"
        }
    }
}'

We can send Audio clips as attachment using below API.

{endpoint}whatsapp/message/send

PARAMETERS

Name Description Limits Required
url Public url of the audio file. Either HTTP or HTTPS link. Upto 16MB Yes
type audio/aac, audio/mp4, audio/amr, audio/mpeg; codecs=opus. (The base audio/ogg type is not supported.) YES YES
caption some text for audio caption N/A No
filename Media file name N/A No

Example Request With Audio Message

cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "channels": [
        {
            "name": "whatsapp",
            "from": "{from}"
        }
    ],
    "recipient": {
        "to": [
            "{receiver}"
        ]
    },
    "message": {
        "type": "audio",
        "payload": {
            "url": "https://file-examples-com.github.io/uploads/2017/11/file_example_MP3_700KB.mp3",
            "caption": "some caption for document",
            "filename": "Sample Audio file"
        }
    }
}'

We can send Video clips as attachment using below API.

{endpoint}whatsapp/message/send

PARAMETERS

Name Description Limits Required
url Public url of the video file. Either HTTP or HTTPS link. Upto 16MB Yes
type video/mp4, video/3gpp (Only H.264 video codec and AAC audio codec is supported.) YES Yes
caption some text for audio caption N/A No
filename Media file name N/A No

Example Request With Video Message

cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "channels": [
        {
            "name": "whatsapp",
            "from": "{from}"
        }
    ],
    "recipient": {
        "to": [
            "{receiver}"
        ]
    },
    "message": {
        "type": "video",
        "payload": {
            "url": "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4",
            "caption": "some caption for document",
            "filename": "Sample video file"
        }
    }
}'
{endpoint}whatsapp/message/send

PARAMETERS

Name Description Limits Required
choices this block contains options list of the message N/A Yes
payload.type if reply message type value should be reply, or list message type value should be list N/A Yes
choices.type if reply message type value should be reply, or list message type value first object should be button and second object should be section N/A Yes

Example Request With Interactive Reply Message

cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "channels": [
        {
            "name": "whatsapp",
            "from": "{from}"
        }
    ],
    "recipient": {
        "to": [
            "{receiver}"
        ]
    },
    "message": {
        "type": "interactive",
        "payload": {
            "type": "reply",
            "header": {
                "type": "text",
                "payload": {
                    "text": "Hello Dear!"
                }
            },
            "body": {
                "type": "text",
                "payload": {
                    "text": "Do you like the whatsapp?"
                }
            },
            "choices": [
                {
                    "type": "reply",
                    "payload": {
                        "title": "Yes",
                        "id": "1"
                    }
                },
                {
                    "type": "reply",
                    "payload": {
                        "title": "No",
                        "id": "2"
                    }
                }
            ]
        }
    }
}'

Example Request With Interactive List Messages

cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "channels": [
        {
            "name": "whatsapp",
            "from": "{from}"
        }
    ],
    "recipient": {
        "to": [
            "{receiver}"
        ]
    },
    "message": {
        "type": "interactive",
        "payload": {
            "type": "list",
            "header": {
                "type": "text",
                "payload": {
                    "text": "Hi Dear!"
                }
            },
            "body": {
                "type": "text",
                "payload": {
                    "text": "Do you like whatsapp?"
                }
            },
            "choices": [
                {
                    "type": "button",
                    "payload": {
                        "title": "Please Choose",
                        "rows": [
                            {
                                "id": "15",
                                "title": "first product",
                                "description": "row-description-content-here"
                            }
                        ]
                    }
                },
                {
                    "type": "section",
                    "payload": {
                        "title": "Choose Anyone",
                        "rows": [
                            {
                                "id": "16",
                                "title": "Yes",
                                "description": "I like whatsapp"
                            },
                            {
                                "id": "17",
                                "title": "No",
                                "description": "I do not like whatsapp"
                            }
                        ]
                    }
                }
            ]
        }
    }
}'
{endpoint}whatsapp/message/send

PARAMETERS

Name Description Limits Required
phone Mobile numbers saved in mobile N/A Yes
name Person name N/A Yes
address Address details of the contact N/A Yes
org Organization details of the contact N/A Yes
emails emails details of the contact N/A Yes
urls urls details of the contact N/A Yes
birthday birthday details of the contact N/A No

Example Request With Vcard Message

cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "channels": [
        {
            "name": "whatsapp",
            "from": "{from}"
        }
    ],
    "recipient": {
        "to": [
            "{receiver}"
        ]
    },
    "message": {
        "type": "contacts",
        "payload": {
            "addresses": [
                {
                    "city": "Bangalore",
                    "country": "India",
                    "country_code": "in",
                    "state": "KA",
                    "type": "Office",
                    "zip": "560078"
                }
            ],
            "phones": [
                {
                    "phone": "91901912xxxx",
                    "type": "HOME"
                }
            ],
            "emails": [
                {
                    "email": "hello@domin-name.com",
                    "type": "WORK"
                }
            ],
            "urls": [
                {
                    "url": "https://www.domin-name.com",
                    "type": "WORK"
                }
            ],
            "name": {
                "first_name": "Laxman",
                "formatted_name": "Laxman Ka",
                "last_name": "Ka"
            },
            "org": {
                "company": "Company Name",
                "department": "Product",
                "title": "Manager"
            },
            "birthday": "1993-08-18"
        }
    }
}'
{endpoint}whatsapp/message/send

PARAMETERS

Name Description Limits Required
longitude Longitude of the location coordinates N/A Yes
latitude Latitude of the location coordinates N/A No
name Address name N/A No
address Textual representation of location N/A No

Example Request With Location Message

cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "channels": [
        {
            "name": "whatsapp",
            "from": "{from}"
        }
    ],
    "recipient": {
        "to": [
            "{receiver}"
        ]
    },
     "message" : {
        "type": "location",
        "payload" : {
            "longitude": 12.912985,
            "latitude": 77.599505,
            "name": "MOBtexting Pvt Ltd",
            "address": "JP Nagar, Mini forest"
        }
    }
}'

Example Request With Template “HSM” (Highly Structured Message)

curl -X POST \
  '{endpoint}whatsapp/message/send' \
  -H 'authorization: Bearer d9e1cac3812186b353c5022xxxxx' \
  -H 'content-type: application/json' \
  -d '{
	"channels": [{
		"name": "whatsapp",
		"from": "919019120xxx"
	}],
	"recipient": {
		"to": "91XXXXXX"
	},
	"message": {
		"type": "template",
		"payload": {
			"name": "otp",
			"language": "en",
			"components": [{
					"type": "header",
					"parameters": [{
						"type": "text",
						"text": "replacement_text"
					}]
				},
				{
					"type": "body",
					"parameters": [{
							"type": "text",
							"text": "replacement_text"
						},
						{
							"type": "currency",
							"currency": {
								"fallback_value": "$100.99",
								"code": "USD",
								"amount_1000": 100990
							}
						},
						{
							"type": "date_time",
							"date_time": {
								"fallback_value": "February 25, 1977",
								"day_of_week": 5,
								"day_of_month": 25,
								"year": 1977,
								"month": 2,
								"hour": 15,
								"minute": 33
							}
						},
						{
							"...": "..."
						}
					]
				},
				{
					"type": "button",
					"sub_type": "quick_reply",
					"index": "0",
					"parameters": [{
						"type": "payload",
						"payload": "aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
					}]
				},
				{
					"type": "button",
					"sub_type": "url",
					"index": "1",
					"parameters": [{
						"type": "text",
						"text": "9rwnB8RbYmPF5t2Mn09x4h"
					}]
				},
				{
					"type": "button",
					"sub_type": "url",
					"index": "2",
					"parameters": [{
						"type": "text",
						"text": "ticket.pdf"
					}]
				}
			]
		}
	}
}'

Example Product Shipment Request With Template

curl -X POST \
  '{endpoint}whatsapp/message/send' \
  -H 'authorization: Bearer d9e1cac3812186b353c5022xxxxx' \
  -H 'content-type: application/json' \
  -d '{
	"channels": [{
		"name": "whatsapp",
		"from": "919019120xxx"
	}],
	"recipient": {
		"to": "91XXXXXX"
	},
	"message": {
		"type": "template",
		"payload": {
			"name": "oculus_shipment_update",
			"language": "en",
			"components": "components": [{
				"type": "header",
				"parameters": [{
					"type": "image",
					"image": {
						"link": "link-to-your-image"
					}
				}]
			},
			{
				"type": "body",
				"parameters": [{
						"type": "text",
						"text": "Anand"
					},
					{
						"type": "text",
						"text": "Quest"
					},
					{
						"type": "text",
						"text": "113-0921387"
					},
					{
						"type": "date_time",
						"date_time": {
							"fallback_value": "23rd Nov 2019",
							"day_of_month": "20",
							"year": "2019",
							"month": "9"
						}
					}
				]
			},
			{
				"type": "button",
				"index": "0",
				"sub_type": "url",
				"parameters": [{
					"type": "text",
					"text": "1Z999AA10123456784"
				}]
			}
		]
		}
	}
}'