Webhooks

Webhooks enable you to harmonize your current system with Helios SMS. In this guide, we will walk you through the steps of setting up a webhook integration with the Helios SMS API to transmit customer data from your system to Helios SMS.

Customers

The Helios SMS Webhook API allows you to push customer information to the Helios SMS platform. The endpoint for this service is:

POST https://api.sendhelios.com/v1/customer

You will transmit data to this endpoint via a POST request, with the data structured according to the following JSON structure:

{
  "apiKey": "Your-API-Key",
  "customer": {
    "phoneNumber": "Customer's phone number",
    "firstName": "Customer's first name (optional)",
    "lastName": "Customer's last name (optional)",
    "email": "Customer's email (optional)"
  },
  "properties": "Additional properties (optional)",
  "addToLists": [
    "List 1",
    "List 2",
    "..."
  ],
  "removeFromLists": [
    "List 1",
    "List 2",
    "..."
  ]
}

JSON Definitions

Here's a breakdown of the JSON structure:

• apiKey (required): This is your unique Helios SMS API key. It identifies your account and authorizes the API call.
• customer (required): This object contains the customer's details.
• phoneNumber (required): The customer's phone number.
• firstName (optional): The customer's first name.
• lastName (optional): The customer's last name.
• email (optional): The customer's email address.
• properties (optional): An additional JSON object that can be used to send extra data about the customer.
• addToLists (optional): An array of lists to which the customer should be added. These should be the unique identifiers of the lists.
• removeFromLists (optional): An array of lists from which the customer should be removed. These should be the unique identifiers of the lists.

Messages

You can use webhooks to send messages directly to customers

POST https://api.sendhelios.com/v1/messages

When sending messages you must include your API key as a header in the request:

Authorization: bearer {apiKey}

{
  "body": "Your message here",
  "customer": {
    "phoneNumber": "Customer's phone number",
    "firstName": "Customer's first name (optional)",
    "lastName": "Customer's last name (optional)",
    "email": "Customer's email (optional)"
  }
}

Setting up the Webhook

To set up the webhook integration, follow these steps:

1. In your system, create a service or script that is capable of sending an HTTP POST request to the provided API endpoint. The specific implementation details will depend on your system and its programming language.
2. Gather the necessary data according to the JSON structure. Remember to replace Your-API-Key with your actual Helios SMS API key.
3. Structure your data as a JSON object and include it in the body of your POST request.
4. Set the 'Content-Type' header of your POST request to 'application/json'.
5. Send the POST request to the API endpoint.

That's all! Once the webhook is set up, your system will be capable of sending customer data to Helios SMS.

Troubleshooting

If you encounter issues, ensure to verify the following:

1. Verify that you're correctly formatting your data as a JSON object.
2. Confirm that your API key is valid and you're correctly including it in the apiKey field.
3. If you're trying to add or remove customers from lists, ensure the list identifiers are correct.

If you're still facing problems after checking these steps, please reach out to our support team for assistance.

Conclusion

Webhooks provide a powerful tool to integrate your systems with Helios SMS, enabling automated transfer of customer information. With this guide, you should be able to successfully establish a webhook integration with the Helios SMS API.