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!

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!

Convert Speech to Text
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.

Endpoint: `/auth/create_user`

Method: POST

This endpoint creates a new user in Botlhale AI APIs and sends an email to the provided email.

Request Body

The request body should include the following fields:

email (str) - Required The email address for the new user.

Response

The API returns a JSON object along with an HTTP status code.

Successful User Creation:

Unset 
{
    "message": ""Your username is {email}and temporary password is {password}."
    }

message (str)

A message indicating the status of user creation.

Endpoint:`/auth/login`

Method: POST

This endpoint authenticates a user using their email and password, returning a new refresh token upon successful login. User is limited to 3 active refresh tokens .

Request Body

The request body should include the following fields:

email (str) - Required

The email address of the user.

password (str) - Required

The password associated with the user's account.

Response

The API returns a JSON object along with an HTTP status code.

Successful Authentication:

Unset
{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

refresh_token (str)

A token that can be used to refresh the user's session.

Endpoint: `/auth/reset_password`

Method: POST

This endpoint initiates the password reset process by sending a confirmation code to the user's email address

Request Body

The request body should include the following field:

email (str) - Required

The email address of the user requesting the password reset.

Response

The API returns a JSON object along with an HTTP status code. Successful Password Reset Initiation:

Unset
{
   "message": "Password reset initiated successfully. Please check your email for further instructions."
}

Endpoint: `/auth/confirm_reset_password`

Method: POST

This endpoint completes the password reset process for a Botlhale AI API user by verifying the confirmation code and setting a new password.

Request Body

The request body must include the following fields:

Request Params	Data Type	Required	Description
email (str)	string	Required	The email address of the user.
confirmation_code	string	Required	The confirmation code sent to the user's email during the password reset initiation.
new_password	string	Required	The new password for the user.

Response

The API returns a JSON object along with an HTTP status code.

Successful Password Reset Confirmation:

Unset
{
    "message": "Password reset confirmed successfully."
}

Endpoint: `/auth/get_tokens`

Method: GET

This endpoint retrieves all refresh tokens associated with a specific user from the api-users table. The tokens are returned in a partially masked format for security purposes.

Request Parameters

The request must include the following query parameter:

email (str) - Required The email address of the user whose refresh tokens are being retrieved.

Response

The API returns a JSON object containing the list of refresh tokens along with an HTTP status code.

Successful Retrieval of Tokens:

Unset 
{
    "refresh_tokens": [
        {
            "token": "abcde****vwxyz",
            "datetime": "2023-10-01T12:34:56.789Z",
            "status": "active",
            "id": "token_id"
        },
        {
            "token": "mnopq****rstuv",
            "datetime": "2023-09-15T08:22:11.567Z",
            "status": "revoked",
            "id": "token_id_2"
        }
    ]
}

token (str)

Partially masked refresh token for security.
datetime (str)

The timestamp when the token was created or last updated.
status (str)

The current status of the token (e.g., active or revoked).
id (str)

A unique identifier for the refresh token.

Endpoint: `/auth/revoke_token`

Method: POST

This endpoint allows a user to revoke a specific refresh token by providing the token ID and their email. The token is revoked from Botlhale AI APIs.

Request Body

The request body must include the following fields:

email (str) - Required

The email address of the user requesting the revocation.

id (str) - Required

The ID of the refresh token to be revoked.

Response

The API returns a JSON object along with an HTTP status code.

Successful Token Revocation:

Unset
{
    "message": "Refresh token revoked successfully."
}

Endpoint: `/auth/generate`

Method:POST

This endpoint generates a new authentication token by refreshing an existing one using the provided refresh token.

Request Body

The request body should include the following field:

refresh_token (str) - Required

The refresh token used to generate a new authentication token.

Response

The API returns a JSON object along with an HTTP status code.

Successful Token Generation:

Unset
{
    "token": "new_auth_token_abc123",
    "expires": 3600
}

token (str)

The newly generated authentication token.
expires (int)

The time in seconds until the token expires (e.g., 3600 seconds = 1 hour).

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
generate	`string`	Required	This endpoint generates a new authentication token by refreshing an existing one using the provided refresh token.

Request Example

Python
JavaScript
NodeJs - Request
cURL

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

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

headers = {}

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

print(response.text)

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

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

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

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

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

curl --location --request POST 'https://api.botlhale.io/generate' \
--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).

Contact us

info

We are here to help! Please contact us with any questions.

Getting Started

Supported Languages​

Quickstart Guide​

Authentication​

Endpoint: /auth/create_user​

Request Body​

Response​

Endpoint:/auth/login​

Request Body​

Response​

Endpoint: /auth/reset_password​

Request Body​

Response​

Endpoint: /auth/confirm_reset_password​

Request Body​

Response​

Endpoint: /auth/get_tokens​

Request Parameters​

Response​

Endpoint: /auth/revoke_token​

Request Body​

Response​

Endpoint: /auth/generate​

Request Body​

Response​

Response body​

Response Codes​

Contact us​

Supported Languages

Quickstart Guide

Authentication

Endpoint: `/auth/create_user`

Request Body

Response

Endpoint:`/auth/login`

Request Body

Response

Endpoint: `/auth/reset_password`

Request Body

Response

Endpoint: `/auth/confirm_reset_password`

Request Body

Response

Endpoint: `/auth/get_tokens`

Request Parameters

Response

Endpoint: `/auth/revoke_token`

Request Body

Response

Endpoint: `/auth/generate`

Request Body

Response

Response body

Response Codes

Contact us