Getting Started

Botlhale AI's APIs are organised around REST. Our APIs have predictable resource-oriented URLs; accept form-encoded request bodies; return JSON-encoded responses; and use standard HTTP response codes and authentication. See the Response Codes and Authentication sections of this documentation for additional information.

Supported Languages

The following table shows the languages Botlhale AI currently supports. The table also indicates the speech tasks supported for each language. Our team is always working to add new languages to the list.

Language	Region	Code	Translation	ASR	TTS	Diarization	Language ID
English	South Africa	en-ZA	√	√	√	√	√
isiZulu	South Africa	zu-ZA	√	√	√	√	√
isiXhosa	South Africa	xh-ZA	√	√	√	√	√
Sesotho	South Africa	st-ZA	√	√	-	√	√
Setswana	South Africa	tn-ZA	√	√	√	√	√
Sepedi	South Africa	nso-ZA	√	√	√	√	√
Tshivenda	South Africa	vr-ZA	-	√	√	√	√
Xitsonga	South Africa	ts-ZA	√	√	-	√	√
Afrikaans	South Africa	af-ZA	√	√	√	√	√
Kiswahili	Kenya	sw-KE	√	√	√	√	-
Kinyarwanda	Rwanda	rw-RW	√	√	-	-	-

Quickstart Guide

Chatbot APIs

See what you can do with our Chatbot API!

1. Start a Conversation with text or speech

info

Use the following links to view examples of how you can integrate our APIs on different platforms.

Flask Template Facebook Template WhatsApp Template

Speech API

See what you can do with our Speech API!

1. Convert Speech to Text
2. Convert Text to Speech

Authentication

The Botlhale AI APIs use API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-facing code, and so on.

Authentication to all API endpoints is performed via Bearer Authentication. Bearer Authentication (also called token authentication) is an HTTP authentication scheme that makes use of security tokens called "bearer tokens". Bearer Authentication can be understood as "giving access to the bearer of this token". The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources.

To perform Bearer Authentication, you need to use the REFRESH_TOKEN made available to you upon sign-up. This refreshToken  does not expire and is used to generate the API key you will use to interact with the API endpoints.

Authorization: Bearer <IdToken>

tip

You can get your API keys by going navigating to Settings > General Settings > API on the platform.

warning

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Generate a Bearer Token POST

Authorization: Bearer <IdToken>

This endpoint generates a bearer auth token for secure access to our APIs.

Request Params	Data Type		Description
REFRESH_TOKEN	String	Required	Refresh token used to generate a new authentication token.

Request Example

Request Params	Data Type		Description
REFRESH_TOKEN	string	Required	Refresh token used to generate a new authentication token.

Request Example

Python

import requests
url = "https://api.botlhale.xyz/generateAuthToken"

payload={'REFRESH_TOKEN': <REFRESH_TOKEN>,}
files=[]

headers = {}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

JavaScript

var formdata = new FormData();
formdata.append("REFRESH_TOKEN", REFRESH_TOKEN);

var requestOptions = {
method: 'POST',
body: formdata,
redirect: 'follow'
};

fetch("https://api.botlhale.xyz/generateAuthToken", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));   

NodeJs - Request

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.botlhale.xyz/generateAuthToken',
  'headers': {

  },
  formData: {
    'REFRESH_TOKEN': '<IdToken>'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

cURL

curl --location --request POST 'https://api.botlhale.io/generateAuthToken' \
--form 'REFRESH_TOKEN=<REFRESH_TOKEN>'

Response body

{
    "AuthenticationResult": {
        "AccessToken": "<AccessToken>",
        "ExpiresIn": 86400,
        "IdToken": "<IdToken>",
        "TokenType": "Bearer"
    },
    "ChallengeParameters": {}
}

API Authentication

Include IdToken as the Bearer Token in headers for Authorization on other API endpoints. All API endpoints require a Bearer Token in the header. For example:

headers = {"Authorization": "Bearer <IdToken>"}

Response Codes

Botlhale AI uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• Codes in the 2xx range indicate success
• Codes in the 4xx range indicate an error stemming from the information provided (for example, a required parameter was omitted, a charge failed, and so on)
• Codes in the 5xx range indicate an error stemming from Botlhale's servers (these are rare)

Successfully executed operations return 2xx codes, and, where appropriate, they return the requested information directly in the response body. The following table shows the typical response codes, entities and headers used for the various HTTP verbs supported by the APIs.

HTTP Status Code Summary	Description
200 - OK	Everything worked as expected.

As previously mentioned, unsuccessfully executed operations return either a 4xx or 5xx response code. In the case where a standard HTTP error is sufficiently descriptive, for example, 401 (Not Authorized), or 404 (Not Found), the response body remains empty. In other cases, we use a generic response code for input errors (400), and the response body includes an error entity with additional details on the error, including an application error code and a human readable error description. The format of this error entity is shown in the following table.

HTTP Status Code Summary	Description
400 - Unauthorized	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on Botlhale's end (these are rare).