HSMs (english)

Access through the Chat-Tonic API

Sending a simple HSM

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:

“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

Sending a HSM campaign

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:

“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"

• 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

GET sent HSMs

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.