Developers
Call chatbots, flows and automations from your own systems with the Buni.ai public API, and receive events back.
The Buni.ai public API lets your backend talk to a project you built in the app. You create a token in the project's settings, then call the project over HTTPS.
What you can do
| Task | Endpoint | Project type |
|---|---|---|
| Send a user message to a bot and get its reply | POST /bots/{projectId}/message | Chatbot |
| Queue a bot message and get the reply later | POST /bots/{projectId}/invoke | Chatbot |
| Start a chatbot flow from an event in your system | POST /flows/{projectId}/trigger, /trigger-async | Chatbot |
| Run an automation workflow | POST /automations/{projectId}/trigger, /trigger-async | Automation |
| Schedule a run for later, then cancel or move it | runAt or delaySeconds, then PATCH /external-invocations/{invocationId} | Chatbot, Automation |
| Check a run's status and result | GET /external-invocations/{invocationId} | Chatbot, Automation |
| Poll one of your APIs for new items and run a flow per item | /flows/{projectId}/polling | Chatbot |
| List and replay events that could not be delivered | /flows/{projectId}/dead-letters | Chatbot |
| Start an automation from any service that can send a webhook | The Webhook trigger's URL | Automation |
Chatbot and automation projects only
The API Access tab, and API tokens, exist only for chatbot and automation projects. USSD, SMS and IVR projects cannot be called through this API.
Base URL
https://www.buni.ai/api/v1/orgs/{orgId}{orgId} is your organization ID. You do not need to look it up: the URLs under Settings › API Access › Your Trigger Endpoints already contain it and the project ID.
Use the www. host. The bare buni.ai domain redirects, and most HTTP clients turn a redirected POST into a GET, which fails.
v1 is the only API version. Any other version returns 400 with code: "UNSUPPORTED_API_VERSION".
Quick example
Send a message to a chatbot and print its reply. Replace the IDs and the token with your own.
curl -X POST "https://www.buni.ai/api/v1/orgs/$ORG_ID/bots/$PROJECT_ID/message" \
-H "Authorization: Bearer $BUNI_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "What are your opening hours?", "sessionId": "customer-4821"}'A successful call returns the run's ID, its status and the bot's messages:
{
"invocationId": "clx9k2m4p0001ab12cd34ef56",
"status": "SUCCEEDED",
"result": {
"messages": ["We are open Monday to Friday, 8am to 6pm."],
"actions": []
}
}Every call, sync or async, creates an invocation: a record of one run with its request, result, status and step trace. You see them under Invocation Health in the API Access tab, and read them with GET /external-invocations/{invocationId}.
Before you start
- Build and publish the project. The API runs the published version.
- Create a token with the right scope. See Authentication.
- For a chatbot flow or an automation, check the trigger. Calls are validated against the flow's Trigger node (trigger key and expected payload); see Project API settings.