What is the Chat API?

Mitto’s Chat API lets you choose what platform you want to use to send and receive SMS messages. Using this API, you can create an omnichannel experience for your customers. Part of omnichannel is seamlessly integrating different communication methods so they are in one place for you to review. You can arrange to send and receive messages with WhatsApp, Viber, and Mitto SMS.

The Chat API’s features include:

  • JWT authentication
  • Customer log in and password management
  • Message sending, indexing, and delivery reports. You can track your users’ messages and use the data for marketing or to debug technical issues.
  • Webhook management – set up a webhook to receive information about your messages. You can set up multiple webhooks to separate messages from different sources, then manage them.

Documentation Organization

We organize our documentation as follows:

  • Read details about Mitto’s Chat API including available endpoints and authentication. – Chat API
  • See the Chat API reference page, that shows individual requests and responses.

Get Started with the Mitto Chat API

This section describes how to get started with Mitto’s Chat API. After reading this, you will know how to sign up with Mitto and what endpoints are available.

Sign up for a Mitto Account

To get started with Mitto, do the following:

  1. Sign up for a Mitto account at https://www.mitto.ch/contact/ or write to info@mitto.ch.
  2. Submit the IPs you want to use for requests. They must be whitelisted on Mitto’s system.
  3. Submit the IPs you want to use for requests.  They must be whitelisted on Mitto’s system.
  4. For callbacks, provide your dedicated callback URL and method (both GET and POST methods are supported). If you are using multiple URLs, one or more for each communication channel, you must provide all of them to Mitto for whitelisting.
  5. Mitto will respond with your API key and confirmation that your IP addresses and callback URLs are configured.

Request Requirements

The Chat API endpoints are:

Customers

The Customer endpoint lets you log in a customer or set a customer password.
https://messaging.mittoapi.com/v{version}/Customers/login
Send a POST request to the Customer Login endpoint to check customer email and password.

https://messaging.mittoapi.com/api/v{version}/Customers/changePassword
You can send a POST request to this endpoint to update and change a customer password. This can be used to help customers who lost their password, or to do a routine password change.

Message

The Message endpoint is for sending and monitoring messages on your system.

https://messaging.mittoapi.com/api/v{version}/Message
This endpoint lets you retrieve messages by their ID using a GET request. You can review them to collect data for marketing, technical issues, and more.

https://messaging.mittoapi.com/api/v{version}/Message/send This endpoint lets you use a POST request to send messages using Viber or WhatsApp.

https://messaging.mittoapi.com/api/v{version}/Webhook You can use the webhook endpoint in a variety of ways. With a GET request, you can retrieve a list of all webhooks you have whitelisted with Mitto. With a POST request, you can set up a webhook you would like to use.

https://messaging.mittoapi.com/api/v{version}/Webhook/{id} Using a GET request, if you have the ID for a webhook, you can retrieve details about a specific webhook. With a PUT request, you can select what triggers you want to use for your webhook. Any triggers you set will then cause a notification to be sent to you when they occur. Whenever you make an update, you need to include all the triggers you want to use. An update doesn’t add on to what is there, it replaces what you have.

https://messaging.mittoapi.com/api/v{version}/WebhookTrafficAccount/ApplyWebhookForTrafficAccount With a POST request you can indicate the ID for the webhook you want to direct traffic to. You can use the IDs to split traffic by account.

https://messaging.mittoapi.com/api/v{version}/WebhookTrafficAccount/DeleteWebhookForTrafficAccount Use a DELETE request to remove a traffic account you were directing to the webhook you identified by webhookId.

https://messaging.mittoapi.com/api/v{version}/trafficAccounts/{trafficAccountId}/WhatsAppTemplates Use a GET request to this endpoint with a trafficAccountID included to see what templates are associated with the ID.

https://messaging.mittoapi.com/api/v{version}/trafficAccounts/{trafficAccountId}/WhatsAppTemplates/{name} You can send a POST request to create a new Whats App template to send messages with.

https://messaging.mittoapi.com/api/v{version}/trafficAccounts/{trafficAccountId}/WhatsAppTemplates/{name} You can delete a template from an account if you know its name and the trafficAccountId it is associated with.

Authentication

The Chat API uses JWT authentication. JSON Web Token (JWT) is an open standard (RFC 7519) that defines a self-contained method for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. The token issuer digitally signs, and then the party receiving the token can compare against their copy of the digital signature to prove that the token is legitimate.

Tokens last for one hour, at which point you must retrieve a new token to continue use.

The way everything is set up, you start with your email and password to retrieve a token. You then use the token to authenticate with the other endpoints in the Chat API.

Traffic Account (TA)

A traffic account is a way of splitting up your traffic so you can track it by brands and providers, or any other way you want to split it, such as by events that happen. Each traffic account can only be mapped to one messaging channel, where a messaging channel is defined as something like What’s App, Facebook Messenger, SMS, Viber, or similar. You can then track what happens for each traffic account in a variety of ways by using webhooks (which will be discussed in another section).

Webhooks, Callbacks, 2-Way Communication

Webhooks in the Chat API are defined by two parts:

  • The URL you want to receive callbacks at.
  • Triggers that cause callbacks to be sent. Available triggers include Delivered, Failed, Read, and UserMessage.

You can use webhooks to find out the statuses of your messages, and also to enable two-way communication (which you would do using the UserMessage trigger). You can have as many webhooks as you like, and use these to split up your traffic by trigger. You can also split up traffic by TA. All webhooks are set at the TA level.

For two-way chat, this is grouped into a conversation. The conversation contains details about the participants and the platform they are using.