To use the API, you’ll need to have an API key that needs to be included in all request headers. This key can be generated through the django admin page. Please note that “normal“ users do not have access to this page, so a dimagi employee with the superuser role will have to generate this key for you.

All requests needs to specify the the API key in the X-API-KEY header.

Request headers example

Accept: "application/json"
X-Api-Key: <your-api-key>

Supported Endpoints

List a team’s experiments

URL: https://chatbots.dimagi.com/api/experiments

Method: GET

Response body:

{
  "results": ["name": "experiment 1", "experiment_id": "1cc121f1-e69f-4340-9fef-91daf735f6bc"],
  "next": "<url to the next page>",
  "previous": "<url to the previous page>"
}

Send a message to the bot

URL: https://chatbots.dimagi.com/channels/api/<experiment-id>/incoming_message

Method: POST

Request body:

{
  "message": "Your message for the bot"
}

Response body:

{
  "response": "the bot's response"
}

Add or Update participant data

URL: https://chatbots.dimagi.com/channels/api/participants/<participant-id>

Method: POST

Request body:

{
  "participant-1-id": {"name": "John", "surname": "Doe"},
  "participant-2-id": {"name": "Jane", "surname": "Doe"},
}

Response body:

{
  "errors": []
}