Skip to main content

Sending WhatsApp templates

We have several different ways of sending WhatsApp messages from Hilos with our API, we'll go from the simplest one to the most complex:

  • Send a single WhatsApp message: select a template to use and call our endpoint with the recipient phone number and the variables the template needs. That's it!
  • (SOON) Send broadcasts: select a template to use and call our endpoint with a list of phones + variables, or a csv file containing them.
  • Execute a flow: select a flow to execute and who to execute it for (spoiler: can be a list of contact ids, a .csv file with phone numbers or a set of filters over your saved contacts in Hilos), and get started!

We also have several other endpoints you might be interested in, like:

  • Contacts (CRUD operations)
  • FlowExecutionContacts (Whenever a contact starts a flow, we save everything this contact does during the execution, like answers to questions and messages sent and received).

Single messages

It's extremely easy to send a single message using Hilos.The endpoint is https://api.hilos.io/api/channels/whatsapp/template/{uuid}/send. This uuid parameter is the uuid of the template you wish to send.

You can check which templates are available for you in https://app.hilos.io/template. Please note that only APPROVED templates can be sent, if you get a 404 it's because you specified a template that either doesn't exist or is not yet approved.

*An example of how an approved template looks. The template id is right below the name.*

An example of how an approved template looks. The template id is right below the name.

For now, all templates must be created in 360Dialog's customer hub, we don't yet support creating them in Hilos. Once you create a template, it usually is approved in a few minutes, though officially it can take up to 2 days to be approved.

Hilos syncs all your templates from WhatsApp every 5 minutes, though you can click a button to sync them at any time from that same page.

Once you selected the template to use, you can now call the endpoint! Below is a sample request.

HTTP POST https://api.hilos.io/api/channels/whatsapp/template/<uuid>/send

{
"phone": "+525577664433",
"variables": ["Alfonso", "John", "guide_es.pdf"]
}

If you provide either less or more variables than what the template needs, you'll get back a 400. Also note that the phone number must be in E164 format, and we save it to your contacts automatically.

The templates you use can be as complex as you'd like: you can use a template with 1 header URL (if you're using an image, document or video header) or 1 header variable (for text header),as well as variables in the message body and in a URL type button.

When you send this variable list, we'll assign them to the template in order:

  • We’ll first assign variables to the header, if it requires it,
  • Then body,
  • And last, to buttons.

If you'd like to test out how your template looks and check how many variables you need to set, you can do so by clicking on the template name at https://app.hilos.io/template, you'll see a preview like the following:

*Clicking on the template name opens this preview modal.*

Clicking on the template name opens this preview modal.

As a response, you'll get the id of the message sent, along with the conversation id this message belongs to:

{
"id": "a513da3a-8b73-42aa-a938-0eb1e0141533",
"conversation": "ee49ab6c-dfd8-4cb6-a512-5880f4385622"
}