Dashboard Chat Contract

The Agent HTTP service exposes a low-latency, structured chat endpoint for the SendAfrica dashboard and trusted service proxies. The public SendAfrica API support route is POST https://api.sendafrica.online/v1/support/chat; the Agent service endpoint documented here is POST /v1/agent/chat.

Request

Send one new user turn. The Agent persists the conversation by session_id, so clients should create a stable random session ID per conversation and reuse it for subsequent turns. A session is bound to the X-Account-ID and X-User-ID values supplied by the trusted caller.

POST /v1/agent/chat HTTP/1.1
Authorization: Bearer SA-your-api-key
X-Account-ID: account-uuid
X-User-ID: user-uuid
Content-Type: application/json
 
{
  "session_id": "chat_01J...",
  "message": "Show me my recent SMS delivery failures",
  "user_confirmation": false
}

The Agent accepts either X-API-Key: SA-... or an opaque Authorization: Bearer SA-... API-key credential. JWT-shaped bearer tokens are forwarded as JWT credentials. Production deployments require a caller credential and an account identity.

Structured response

The endpoint retains the familiar response field while adding fields needed for a professional chat interface.

{
  "session_id": "chat_01J...",
  "status": "completed",
  "response": "I found 3 failed messages from the last 24 hours.",
  "confirmation_required": null,
  "tool_events": [
    {
      "tool": "get_usage_summary",
      "status": "completed",
      "duration_ms": 184.3
    }
  ],
  "iterations": 1,
  "request_id": "req_01J..."
}

status is one of completed, confirmation_required, loop_limit, timeout, validation_error, or error. tool_events is ordered in the same order the model requested tools. Independent read-only tools may execute concurrently, so the event duration is useful for progress indicators but should not be interpreted as a global wall-clock sum.

Confirmation workflow

The Agent never silently executes high-impact operations that require confirmation. The following actions return status: confirmation_required before the side effect is performed:

A confirmation response looks like this:

{
  "status": "confirmation_required",
  "response": "Confirmation is required before I execute that action.",
  "confirmation_required": {
    "status": "confirmation_required",
    "action": "create_campaign",
    "summary": "Create campaign Weekend promotion",
    "notice": "Explicit confirmation is required before this side effect is executed.",
    "name": "Weekend promotion",
    "contact_list_id": "list-uuid",
    "message": "This weekend only"
  },
  "tool_events": [
    {"tool": "create_campaign", "status": "confirmation_required"}
  ]
}

Render this as an approval card containing the action, recipient count or audience, message/subject, and explicit Approve and Cancel controls. On approval, resend the user’s confirmation turn with user_confirmation: true. Do not infer approval from a vague message such as “okay?” unless the user has clearly approved the displayed action.

Delivery and SMS semantics

A successful SMS tool response means that SendAfrica accepted the submission for provider processing. It does not mean that a handset has received the message. Use the message log or delivery lookup tool to display sent, delivered, failed, or another terminal provider state.

SMS accounting is calculated by the SendAfrica API. GSM-7 messages use septets, with 160 septets for a single part and 153 septets per part for multipart messages. Unicode messages use UTF-16 code units, with 70 units for a single part and 67 units per part for multipart messages. International credits are destination-rate-card specific; do not present every part as one credit.

Frontend interaction guidance

Show the assistant response as soon as the structured response arrives, and render tool_events as compact progress rows rather than exposing raw tool arguments. Preserve session_id locally. Use request_id when displaying support diagnostics or correlating server logs. For timeout, offer a retry using the same session; for confirmation_required, retain the approval card; for error, show a safe retry message without exposing upstream credentials or stack traces.

The current endpoint returns one final JSON document rather than a token stream. The capability endpoint advertises this explicitly so clients can feature-detect future streaming support:

GET /v1/agent/capabilities

Never put API keys in browser JavaScript. The dashboard should call the authenticated SendAfrica API support route, and the Go support proxy should forward the caller credential to the Agent service over a private trusted connection.