SendAfricaChat API
POST /v1/agent/chat — embed the assistant in your own dashboard. Sessions, per-user credentials, confirmation flow, and response shapes.
/v1/agent/chatAPI Key (`SA-…`) or JWT session tokenThe chat endpoint accepts user input, maintains session history, runs the Ngamia LLM tool-calling loop, and returns either an answer or a safety-confirmation request. It powers the dashboard chat widget and can power yours.
#Request
| Header / Field | Value | Notes |
|---|---|---|
Authorization / X-API-Key | Bearer <jwt> or SA-… key | Forwarded to the core API for every tool call — actions run as that user |
X-Account-Id | account identifier | Scopes session history |
X-User-Id | user identifier | Scopes session history |
session_id | string (body) | Groups the conversation |
message | string (body) | User input |
user_confirmation | boolean (body) | Set true to approve a pending guarded action |
curl -s -X POST https://agent.sendafrica.online/v1/agent/chat \
-H "Authorization: Bearer $JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess-8f3a",
"message": "How many credits do I have left?"
}'#Credential handling
The service inspects the credential you present and swaps it onto its internal API client for the duration of the request, then restores its own credentials. Keys starting with SA- are applied as both X-API-Key and Bearer; strings starting with eyJ are treated as JWTs. This means the agent can never act beyond the permissions of the caller.
#Response shapes
{
"type": "answer",
"session_id": "sess-8f3a",
"reply": "You have 4,820 credits remaining (about 4,820 single-part SMS).",
"tool_calls": [
{ "tool": "get_account_balance", "status": "ok" }
]
}{
"type": "confirmation_required",
"session_id": "sess-8f3a",
"pending_action": {
"tool": "create_campaign",
"summary": "Create campaign 'Friday Sale' to contact list 3 (482 recipients)",
"estimated_credits": 482
},
"reply": "This will schedule a bulk SMS to 482 recipients using ~482 credits. Reply 'confirm' to proceed."
}# Approve the pending action
curl -s -X POST https://agent.sendafrica.online/v1/agent/chat \
-H "Authorization: Bearer $JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess-8f3a",
"message": "confirm",
"user_confirmation": true
}'#Embedding a widget
async function sendToAgent(sessionId: string, message: string, jwt: string) {
const res = await fetch("https://agent.sendafrica.online/v1/agent/chat", {
method: "POST",
headers: {
Authorization: `Bearer ${jwt}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ session_id: sessionId, message }),
});
return res.json(); // { type: "answer" | "confirmation_required", ... }
}
// Render "confirmation_required" payloads as an approve/cancel UI,
// then re-send with user_confirmation: true on approval.CORS is open on /v1/agent/chat (OPTIONS preflight handled), so browser widgets can call it directly. Health probe: GET /health → {"status": "ok"}.