This is a work in progress page, translated from the HSMs (español) version |
The API call has a very simple authentication system with an API key provided by Chat-Tonic, and that is sent in either the HTTP headers or querystring.
The API call receives the following parameters as a JSON in the body:
“id”: phone number, with or without a +, and complete with country code information, e.g.: +54912349876
“hsm”: it’s a JSON object where the HSM information is received. In particular there are 2 required parameters that determine the “template” to be used (namespace, and elementName), and also the “parameters” which are the values for the variables that auto-complete the template. E.g. the HSM might be something like “Welcome {variable} to our WhatsApp customer service support”. Where “{variable}” is replaced with the first value of the “parameters” array, and so on with the rest of the variables.
Inside this object you can also declare the media to send:
media = {
from: 'URL',
type: 'image'|'video'|'document'
url: 'https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg'
} |
“buttonParameter“: it’s an optional string, but mandatory only in the cases where a button of type call to action or dynamic url is on the HSM that has a variable parameter.
“flag”: it’s an optional string. The main purpose is to communicate information to the bot, for it to capture extra information that might be useful in the conversation, which otherwise would be lost in the HSM. E.g: it would be possible to receive the email of the user that is being contacted in the HSM for the bot to use that information for further purposes when the user replies to the HSM.
”agreeHSMConsent”: it’s a boolean, mandatory only for the GupShup platfrom. It provides assurance to Chat-Tonic that the client has obtained consent from the users about receiving this HSM in a previous interaction, through the bot or any other medium.
The following is an example of the API call in CURL:
appCodename is the application codename, specified by Chat-Tonic, and it’s different for every client
accountId is the WhatsApp account id, specified by Chat-Tonic, and it’s different for every client
platform the WhatsApp platform, specified by Chat-Tonic:
whatsapp-gupshup for GupShup accounts
whatsapp-infobip for Infobip accounts
whatsapp-clickatell for Clickatell accounts
whatsapp-movile for Wavy/Movile accounts
appToken the API Key to authenticate the API Call, specified in the Authorization HTTP header, specified by Chat-Tonic, and it’s different for every client
namespace: the namespace for the HSM, specified by Chat-Tonic, and only mandatory for whatsapp-movile, the rest of the platforms can omit it
elementName: the name for the HSM, specified by Chat-Tonic
curl -X POST \
https://chat-tonic.com/api/v1/:appCodename/:platform/:accountId/sendhsm \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer :appToken' \
-d '{ "id": "+54911", "hsm": { "namespace": "template_namespace", "elementName": "template_name", "parameters": [] }, "flag": "optional"}’ |
The API call has a very simple authentication system with an API key provided by Chat-Tonic, and that is sent in either the HTTP headers or querystring.
The API call receives the following parameters as a multi-part form POST in the body, to allow sending files.
“upload”: required, the key name in which the file attachment should come in any of the supported formats
“platform”: must be sent in the querystring, states the name of the platform used to send HSMs. Must be one of the following options:
whatsapp-gupshup for GupShup
whatsapp-infobip for Infobip
whatsapp-clickatell for Clickatell
“accountId”: must be sent in the querystring, states the ID of the account being used to send the HSMs
“date”: optional to be sent in the querystring, a date time in format ISO 8601, which defines when this campaign is to be sent out. It must be a date in the future.
”agreeHSMConsent”: it’s a boolean, mandatory only for the GupShup platfrom. It provides assurance to Chat-Tonic that the client has obtained consent from the users about receiving this HSM in a previous interaction, through the bot or any other medium.
Supported file formats:
XLS: with the following columns:
A: "phone" / “id”
B: "namespace"
C: "elementName"
D: "languageCode"
E: "languagePolicy"
F: "flag"
G: “buttonParameter“
H: "media.from"
I: "media.type"
J: "media.url"
K: "parameter"
L: "parameter"
IMPORTANT: The "parameter" columns need to be sent in the order in which they are defined in the HSM. It can be blank if no parameter is necessary.
IMPORTANT: The file must have a header in row 1 with the above names.
IMPORTANT: The name of the sheet must be "campaign"
CSV: Comma separated values "," with the following format:
"phone (o “id”), namespace, elementName, languageCode, languagePolicy, flag, media.from, media.type, media.url, buttonParameter, parameter, parameter,...\n"
IMPORTANT: The "parameter" columns need to be sent in the order in which they are defined in the HSM. It can be blank if no parameter is necessary.
IMPORTANT: The file must have a header in row 1 with the above names.
JSON: an array of objets with the following keys:
phone / id
namespace
elementName
languageCode
languagePolicy
flag
parameters (array of string)
buttonParameter
media (object)
ZIP, GZ, TAR: Any of the above files, but zip compressed. I.e.: hsms.xlsx.zip
curl --X POST \ 'https://chat-tonic.com/api/v1/demo/hsm/campaign/upload?platform=:platform&accountId=:accountId' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer :userToken' \ --form 'upload=@"~/hsm_campaign.json"' |
To obtain the status of the HSMs sent individually or through a file, you must sent a single parameter in the querystring called query, and inside a JSON object with the field campaignId with the provided string when calling any of the above methods.
curl GET \
'{{baseUrl}}/api/v1/{{codename}}/hsm?query={"campaignId": "xxxxxxxxx"}' \
--header 'Authorization: Bearer :userToken' \
--header 'Content-Type: application/json' \
' |