Skip to main content

Working with Ocelot SMS API

This guide describes how to set up and use the Ocelot SMS API to programmatically send 1:1 texts.

This guide assumes that your account has the necessary permissions and you can create or provide a webhook endpoint on your server to receive delivery status notifications for your messages.

Ocelot SMS API overview#

SMS API is a part of the Ocelot API, which allows you to send a batch of SMS messages (dubbed "1:1 texts" in Admin Portal) in a single request. Once a batch is accepted, Ocelot API will repeatedly call your own SMS webhook URL to notify you about delivery status change of each SMS.

Ocelot SMS API is provided in a form of simple REST API that uses Basic Authentication and uses JSON payloads for simplicity.

You control the batch being sent and process delivery events for each individual message on your side. Ocelot API handles all the heavy-lifting of: validating the batch, checking recipients' phone numbers for opt-outs, registering the resulting 1:1 texts in Admin Portal and everything related to physically delivering your SMS to recipients.

SMS API is also integrated with Admin Portal. Every 1:1 text is immediately available in the Portal, as if it was sent manually.

Prerequisites#

Your chatbot must have the necessary permissions to access Ocelot SMS API granted to you by Ocelot.

Since it's your responsibility to create SMS batches and process incoming events (as stated above), you should be able to provide at least the following to successfully use integrate with Ocelot SMS API:

  • Some arbitrary code (or a program/client/tool) written by you that generates SMS batches and sends them to Ocelot SMS API endpoint via HTTPS;
  • Your own Web Server with a public IP address, which can accept POST requests via HTTP(S);
  • An active phone number available in the Admin Portal, which will be used for sending the batch;
    • It's a good idea to allocate a phone number for SMS API specifically, so it won't be overtaken by a campaign or clash with manually-sent 1:1 texts;
    • Remember that managing phone numbers is your responsibility, but the Admin Portal may help you organization-wise by adding specific labels of your choice to your numbers.

Integrating with Ocelot SMS API#

The following is a high-level overview of communications done between your own infrastructure and Ocelot API. Use it as a guide to develop the necessary components for API integration.

  1. Your code (or a program/client/tool) sends a POST request to https://ai.ocelotbot.com/api/v1/sms/send/, containing a JSON payload with SMS messages.

    • This endpoint requires Basic Authentication
    • Sending is performed from a single phone number and assigned to an operator of your choice;
    • You can see the exact request format in the API documentation.

  2. Ocelot SMS API will validate your request's payload. This phase only validates fields format and the correctness of payload's shape (the format should be as per API documentation linked above).

    • Please see "Responses" section of the API documentation for the exact format of success and error responses;
    • Data in success response includes unique identifiers for the current SMS batch and every message in it. These identifiers will be used later on, when Ocelot API starts calling your webhook to notify you of SMS delivery status changes, so it's a good idea to memorize them.

  3. Once the SMS batch is accepted (the response in the previous request is successful), Ocelot API will enqueue your messages and starts processing them. As soon as message delivery status changes, your SMS webhook URL is notified with a POST request.

    • Please see "Callbacks" section of the API documentation for the exact format response.

Setting up webhook#

Open the Admin Portal and navigate to the "Ocelot API" page

Note: If you don't see "Ocelot API" page in the "Integrations" menu, it's likely that you don't have the necessary permissions. Please contact product support.

Admin Portal - Ocelot API configuration page

Fill the SMS Webhook URL field with the absolute URL of webhook that you've implemented for receiving status change notifications of SMS messages.

Important: Make sure that your webhook URL is available to the outside world. It has to use a public (not private) IP address or a domain that resolves to such.