SDK API

Build custom chat experiences with the AGO SDK API

The SDK API lets you build custom chat interfaces on top of AGO. Use it to manage conversations, send and receive messages, create tickets, and retrieve workspace configuration from your own application.

Base URL

https://your-instance.useago.com/api/sdk/v1/

All endpoint paths below are relative to this base URL.

Authentication

The SDK API uses the same authentication as the embedded widget. Requests are authorized by the X-User-Anon-Id header and validated against your allowed domains list, which you configure in Widget & SDK Configuration.

Include these headers in every request:

curl https://your-instance.useago.com/api/sdk/v1/conversations \
  -H "X-User-Anon-Id: unique_user_id" \
  -H "Origin: https://your-app.com"

Header	Required	Description
X-User-Anon-Id	Yes*	A unique identifier for the current user. X-Widget-Id is the legacy name and still accepted.
Origin	No	The origin domain of your application (validated against allowed domains)
Authorization	No	Bearer {jwt} for authenticated users
X-Widget-Email	No	User email (when not using JWT)
X-Widget-Permission	No	Permission override for the user

*When you send a JWT in the Authorization header, X-User-Anon-Id can be omitted: the user identity is taken from the token’s sub claim.

# JWT-only request — no X-User-Anon-Id needed
curl https://your-instance.useago.com/api/sdk/v1/conversations \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Origin: https://your-app.com"

---

Speech to Text

POST /audio/transcriptions

Converts an audio recording into text. It does not create a conversation or send a message. Show the returned text in your message composer so the user can review it before sending through POST /messages.

Speech to text must be enabled in the tenant configuration; it is off by default. Check permissions[].speech_to_text_enabled in GET /config before showing a recording control. Disabled tenants receive 403 when uploading audio.

Send a multipart/form-data body with one required file field. Supported file extensions: .flac, .mp3, .mp4, .mpeg, .mpga, .m4a, .ogg, .wav, .webm. Maximum file size: 25 MB. The same widget or JWT authentication headers used for messages apply here.

curl https://your-instance.useago.com/api/sdk/v1/audio/transcriptions \
  -H "X-User-Anon-Id: unique_user_id" \
  -H "Origin: https://your-app.com" \
  -F "file=@recording.webm;type=audio/webm"

Response:

{"text": "How do I reset my password?", "transcription_id": "a142c43e-a21a-420e-8246-249d30c7c193"}

When sending the reviewed draft to POST /messages, include transcription_ids with the returned ID (or several IDs if the draft combines recordings):

{
  "content": "How do I reset my password?",
  "transcription_ids": ["a142c43e-a21a-420e-8246-249d30c7c193"]
}

For multipart message requests, send transcription_ids as a JSON array string. Each ID must belong to the authenticated user and can be attached to only one message; unavailable IDs return 400. Up to 100 IDs can be attached to one message. Conversation history returns used_speech_to_text: true for messages with linked dictations, including edited drafts. Discard the IDs if the user clears the draft. Omitting the field preserves the ordinary text-message behavior.

Status	Meaning
400	Empty, unsupported, or unreadable audio
401	Authentication failed
403	Speech to text is disabled for this tenant
413	File exceeds 25 MB
422	Missing file or no speech detected
503	Transcription is temporarily unavailable

Errors use the standard SDK error envelope. Browser recordings require HTTPS (or localhost), microphone permission, and a browser that supports audio recording. Embedded applications also need microphone permission on their iframe.

---

Conversations

List Conversations

GET /conversations

Returns a paginated list of the authenticated user’s conversations.

Query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	50	Number of items per page

Example request:

curl "https://your-instance.useago.com/api/sdk/v1/conversations?page=1&page_size=20" \
  -H "X-User-Anon-Id: unique_user_id"

Example response:

{
  "object": "list",
  "data": [
    {
      "object": "conversation",
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "title": "Help with billing",
      "created_at": "2025-01-15T10:30:00Z",
      "last_message_at": "2025-01-15T11:00:00Z"
    }
  ],
  "has_more": false,
  "total": 1
}

Get Unread Count

GET /conversations/unread

Returns the number of unread conversations and the ID of the most recent unread conversation.

Example request:

curl "https://your-instance.useago.com/api/sdk/v1/conversations/unread" \
  -H "X-User-Anon-Id: unique_user_id"

Example response:

{
  "unread_count": 3,
  "last_unread_conversation_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

Get Conversation

GET /conversations/{conversation_id}

Returns a single conversation with all its messages.

Path parameters:

Parameter	Type	Description
conversation_id	string (UUID)	The conversation ID

Example request:

curl "https://your-instance.useago.com/api/sdk/v1/conversations/a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "X-User-Anon-Id: unique_user_id"

Example response:

{
  "object": "conversation",
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "title": "Help with billing",
  "created_at": "2025-01-15T10:30:00Z",
  "last_message_at": "2025-01-15T11:00:00Z",
  "messages": [
    {
      "object": "message",
      "id": "f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
      "content": "Hello, I need help with my invoice.",
      "role": "user",
      "status": "DONE",
      "created_at": "2025-01-15T10:30:00Z",
      "agent": null,
      "sources": [],
      "attachments": [],
      "tool_call_data": [],
      "follow_up_replies": []
    },
    {
      "object": "message",
      "id": "b9a8c7d6-5432-10fe-dcba-abcdefabcdef",
      "content": "I found your invoice. Here is the current status.",
      "role": "assistant",
      "status": "DONE",
      "created_at": "2025-01-15T10:30:05Z",
      "agent": {
        "id": "e5f6a7b8-1234-5678-9abc-def012345678",
        "name": "Billing Agent"
      },
      "sources": [
        {
          "id": "c1d2e3f4-0000-1111-2222-333344445555",
          "title": "Invoice FAQ",
          "url": "https://help.example.com/invoices"
        }
      ],
      "attachments": [
        {
          "id": "d4e5f6a7-1111-2222-3333-444455556666",
          "name": "invoice_guide.pdf",
          "content_type": "application/pdf",
          "file_size": 204800,
          "file_url": "https://your-instance.useago.com/files/d4e5f6a7.pdf",
          "is_safe_image": false
        }
      ],
      "tool_call_data": [
        {
          "tool_call_data": true,
          "id": "a7b8c9d0-1111-2222-3333-444455556666",
          "status": "done",
          "tool_name": "lookup_invoice",
          "tool_display_name": "Look up invoice",
          "thread": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" },
          "type": "status_message",
          "message": "Invoice #4521 — paid",
          "result": { "message": "Invoice #4521 — paid" },
          "variant": "success"
        }
      ],
      "follow_up_replies": []
    }
  ]
}

Each message includes a tool_call_data array listing the tool calls the agent made while producing that message, in the order they ran. The array is empty when no tool was used. Each entry carries the tool’s status, tool_name, a display name, and a type that tells your interface how to render it (for example status_message, progress_indicator, confirmation_input, or form). Calls to your own client-side functions also include an arguments object with the values the function was called with, so you can show what ran. This is the same shape used by the built-in chat interface, so you can replay a past conversation — including its tool calls — in a custom UI.

---

Messages

Send Message

POST /messages

Sends a message and returns a streaming response using Server-Sent Events (SSE).

This endpoint returns a text/event-stream response. You need an SSE-compatible client to consume the stream. If the stream disconnects, use the Get Message Status endpoint to poll for the final result.

JSON request body:

Field	Type	Required	Description
content	string	Yes	The message text
conversation_id	string (UUID)	No	ID of an existing conversation. Omit to start a new one. The response may return a different conversation ID — see Forked conversations.
agent_id	string (UUID)	No	Target a specific agent
client_functions	array	No	Client-side function definitions the agent can call
client_functions_mode	string	No	How the agent handles client function calls: placeholder (default) or pause. See Continue Message.
metadata	object	No	Widget metadata stored on the user. A nonempty object replaces that user’s previous widget metadata.
hidden	boolean	No	Mark the message as an event sent by your application code, not typed by the user (for example “the user completed the payment”). The agent reads it and replies as usual, but the message is stored and returned with role: "system" so your interface can skip rendering it as a user bubble. Requires conversation_id — a hidden message cannot start a conversation.

Example request (JSON):

curl -N "https://your-instance.useago.com/api/sdk/v1/messages" \
  -H "X-User-Anon-Id: unique_user_id" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I update my payment method?",
    "conversation_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }'

File uploads: To attach files, send the request as multipart/form-data with content, conversation_id, and agent_id as form fields and files for file attachments.

curl -N "https://your-instance.useago.com/api/sdk/v1/messages" \
  -H "X-User-Anon-Id: unique_user_id" \
  -F "content=Here is the screenshot of the error" \
  -F "conversation_id=a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -F "files=@screenshot.png"

Response: The response is a text/event-stream. Each event is a line of text prefixed with data: . Events that belong to a conversation carry it as thread.id; error events such as a rejected file upload carry type and error instead, and end the stream.

Forked conversations

A conversation belongs to the user who started it. If someone else sends a message to it — most often because a conversation link was shared with them — AGO does not add their message to the original. It creates a copy owned by the new sender, seeded with the conversation history, and continues there. The original owner never sees the new sender’s messages, and the new sender’s replies stay private to them.

When this happens, the stream opens with a conversation_forked event before any content:

{
  "conversation_forked": {
    "from": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "to": "9f8e7d6c-5432-10ab-cdef-0987654321ba",
    "reason": "not_conversation_owner"
  },
  "thread": { "id": "9f8e7d6c-5432-10ab-cdef-0987654321ba" }
}

Every later event in that stream, and the answer itself, belongs to the to conversation.

What your integration must do: store the returned ID and use it for subsequent requests. If you keep sending the original conversation_id, your messages are not lost — repeated sends from the same user resolve to the same copy — but GET /conversations/{original_id} keeps returning the original conversation, which never gains the new turns. Your interface would appear frozen while the agent answers into a conversation you never read.

The same conversation_forked object is returned by Get Message Status, so a client that polls after a dropped stream sees it too.

Forking does not apply when the sender is a staff member replying from the agent console, nor to conversations that arrive over Slack, WhatsApp, Messenger or HelpScout, which are shared by design.

What a copy contains: the message text and roles of the conversation so far, capped at the most recent 200 messages. Knowledge sources, file attachments, tool call details and follow-up suggestions are not copied, so messages in a copy are thinner than in the original.

A copy is seeded that way only when the sender could already read the original — with conversation link sharing on, that is anyone holding the link. If your workspace has link sharing turned off, the sender still keeps their message and still gets an answer, but the copy starts empty: no history and no title, since the title is written from the original’s content. They were never able to open that conversation, so nothing from it reaches them.

Carried-over messages are attributed to the new sender, not to whoever shared the conversation, and are returned exactly like any other message. From the moment the copy exists it is that sender’s own conversation, and nothing in a later GET /conversations/{id} marks it as a copy. If you want to show your users that a fork happened, do it once from the conversation_forked event on the stream — it is a notice about the moment, not a permanent property of the conversation.

Stop Message

POST /messages/{message_id}/stop

Stops a turn that is still generating — the equivalent of a “stop” button in your chat UI.

The agent winds down at its next safe point rather than instantly: any tool already running finishes, but no further tools or reasoning rounds start. The text produced up to that point is kept, and the message ends as CANCELED.

Closing the SSE connection on its own does not stop the agent — it keeps generating and the full answer appears the next time you load the conversation. Call this endpoint as well as closing the stream.

Path parameters:

Parameter	Type	Description
message_id	string	The id of the assistant message being generated

Response:

{ "status": "stopping", "message_status": "IN_PROGRESS" }

status is stopping when the request was accepted, not_running when the turn had already finished — stopping a completed turn is harmless, so you can call this without checking first — or not_supported for a background agent run, which cannot currently be stopped once started.

If the turn is paused waiting for client functions, cancellation is immediate: the response is {"status": "stopped", "message_status": "CANCELED"}.

Example:

curl -X POST "https://your-instance.useago.com/api/sdk/v1/messages/{message_id}/stop" \
  -H "X-User-Anon-Id: unique_user_id"

Continue Message

POST /messages/{message_id}/continue

Resumes an agent turn that paused on client function calls. Only relevant when you send messages with client_functions_mode: "pause".

The two modes differ in when the agent sees your function results:

• placeholder (default): when the agent calls one of your client functions, the turn continues immediately without the result. Submitted results are recorded, but the agent’s conversation history retains the invocation placeholder. Use pause when the agent needs the function result to continue.
• pause: the turn stops when the agent calls your client function(s). The SSE stream ends with a status: "WAITING_CLIENT" event that lists waiting_tool_call_ids. Execute each function, submit its result via POST /tool-calls/{id}/submit (body: {"formData": {...}}), then call this endpoint. The agent continues the same turn with the real results — useful when a function changes what the agent should do next (for example a page navigation followed by filling the destination page).

The pause survives page reloads: reload the conversation with Get Conversation, look for an assistant message with status: "WAITING_CLIENT" and tool calls in waiting_input status, then submit and continue as usual.

Path parameters:

Parameter	Type	Description
message_id	string (UUID)	The paused assistant message ID (from the WAITING_CLIENT event)

JSON request body:

Field	Type	Required	Description
client_functions	array	No	The CURRENT page’s function definitions (the page may have changed since the pause)
client_context	object	No	Fresh client context snapshot

Example flow:

# 1. The submit response tells you when the turn is ready to resume
curl "https://your-instance.useago.com/api/sdk/v1/tool-calls/{tool_call_id}/submit" \
  -H "X-User-Anon-Id: unique_user_id" \
  -H "Content-Type: application/json" \
  -d '{"formData": {"navigated": true}}'
# -> {"status": "completed", "result": {...}, "resume": {"message_id": "...", "ready": true}}

# 2. Once ready, resume the turn (returns a new SSE stream)
curl -N "https://your-instance.useago.com/api/sdk/v1/messages/{message_id}/continue" \
  -H "X-User-Anon-Id: unique_user_id" \
  -H "Content-Type: application/json" \
  -d '{"client_functions": [...]}'

A turn that called several client functions resumes only once every one of them has been submitted — the submit response’s resume.ready flag flips to true on the last one. Sending a new message to the conversation abandons any paused turn. The endpoint returns 409 if the message is not paused, if some tool calls are still waiting, or if the conversation moved on.

Response: a text/event-stream, same format as Send Message.

Get Message Status

GET /messages/{message_id}/status

Poll the current status of a message. Use this as a fallback when the SSE stream disconnects or as an alternative to streaming.

Path parameters:

Parameter	Type	Description
message_id	string (UUID)	The message ID

Example request:

curl "https://your-instance.useago.com/api/sdk/v1/messages/f1e2d3c4-5678-90ab-cdef-abcdefabcdef/status" \
  -H "X-User-Anon-Id: unique_user_id"

Example response:

{
  "object": "message_status",
  "id": "f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
  "message_id": "f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
  "conversation_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "content": "You can update your payment method in Settings > Billing.",
  "status": "DONE",
  "agent": {
    "id": "e5f6a7b8-1234-5678-9abc-def012345678",
    "name": "Billing Agent"
  },
  "sources": [
    {
      "id": "c1d2e3f4-0000-1111-2222-333344445555",
      "title": "Payment Methods",
      "url": "https://help.example.com/payments"
    }
  ],
  "ask_to_talk_to_human": false,
  "conversation_forked": null
}

The status field is one of:

Status	Meaning
TODO	The message is queued and has not started processing yet
IN_PROGRESS	The agent is still generating a response
DONE	The response is complete
ERROR	An error occurred while generating the response
CANCELED	The message was canceled before completion
WAITING_APPROVAL	A background agent run is waiting for a staff member to approve a sensitive tool action
WAITING_CLIENT	The turn is paused on client function calls — submit the results, then use Continue Message

Background Agent Results

Message status responses and conversation history messages include background_agent, the current state of the latest linked background run, or null when none is available. It can initially be null while queued work has not started.

Field	Meaning
run_id	Identifier of this run. A new task has a new identifier; approval and resume continue the existing run.
execution_status	"pending", "running", "done", "failed", or "waiting_approval". "done" means execution ended normally or at a controlled stop; "failed" means a technical execution failure. Neither describes whether the objective was achieved.
outcome	"completed", "incomplete", or "failed". null means no recorded outcome, including active and older runs.
checklist	Ordered array of steps, [] for a known empty plan, or null when unavailable. Each step has name, status, and nullable reason. Step statuses are "pending", "in_progress", "completed", "failed", and "not_completed".
completion_notice	Nullable explanation of a limitation. The returned message content already includes this notice; do not append it again.

Use outcome to display the result. Message status: "DONE" means a report was delivered; that report can describe incomplete work, even after an execution error. A "failed" outcome has explanatory fallback content and message status "ERROR". Neither an ended execution nor all checklist steps being completed is sufficient to infer a completed objective.

Replace the displayed checklist when updated run state arrives, including an empty list. The final checklist replaces the live plan; do not match or merge steps by name or position. Keep each message’s run state separate so a new task does not replace the previous task’s results. Treat missing historical outcomes as unknown, rather than deriving success from message status.

Submit Feedback

POST /messages/{message_id}/feedback

Submit positive or negative feedback for an agent response, optionally with what went wrong.

Path parameters:

Parameter	Type	Description
message_id	string (UUID)	The message ID

Request body:

Field	Type	Required	Description
rating	string	Yes	"positive" or "negative"
reasons	array of strings	No	What went wrong. Any of inaccurate, incomplete, information_not_found, technical_issue. At most 4 entries
comment	string	No	Free-text detail from the user. At most 5,000 characters

rating on its own records the thumbs up or thumbs down. Sending reasons, a comment, or both also files a feedback report, which appears in the Feedback tab of the dashboard alongside reports submitted from the chat interface — see Feedback Analytics.

A message holds one report. Submitting feedback again for the same message replaces the previous reasons and comment rather than filing a second report.

A reason outside the four listed values is rejected with 422 and named in the response, so a typo fails rather than being dropped silently.

Example request:

curl -X POST "https://your-instance.useago.com/api/sdk/v1/messages/f1e2d3c4-5678-90ab-cdef-abcdefabcdef/feedback" \
  -H "X-User-Anon-Id: unique_user_id" \
  -H "Content-Type: application/json" \
  -d '{"rating": "positive"}'

Example request with a report:

curl -X POST "https://your-instance.useago.com/api/sdk/v1/messages/f1e2d3c4-5678-90ab-cdef-abcdefabcdef/feedback" \
  -H "X-User-Anon-Id: unique_user_id" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": "negative",
    "reasons": ["inaccurate", "information_not_found"],
    "comment": "The price it quoted is from last year."
  }'

Response: 204 No Content

---

Tickets

Create Ticket

POST /tickets

Creates a support ticket. Send as multipart/form-data to support file attachments.

Form fields:

Field	Type	Required	Description
subject	string	Yes	Ticket subject line
body	string	Yes	Ticket description
priority	string	No	low, medium (default), high, or urgent
typology	string	No	technical, billing, or general (default)
conversation_id	string (UUID)	No	Link the ticket to an existing conversation
email	string	No	Requester email address
custom_fields	string (JSON)	No	JSON-encoded array of {"id": "field-id", "value": "val"}
ticket_form_id	string (UUID)	No	ID of a specific ticket form to use
files	file(s)	No	File attachments

Example request:

curl -X POST "https://your-instance.useago.com/api/sdk/v1/tickets" \
  -H "X-User-Anon-Id: unique_user_id" \
  -F "subject=Cannot access dashboard" \
  -F "body=I get a 403 error when I try to open the analytics page." \
  -F "priority=high" \
  -F "email=[e-mail]" \
  -F "files=@error_screenshot.png"

Example response (201 Created):

{
  "object": "ticket",
  "id": "t1u2v3w4-5678-90ab-cdef-1234567890ab",
  "url": "https://your-instance.useago.com/tickets/t1u2v3w4-5678-90ab-cdef-1234567890ab"
}

---

Configuration

Get Config

GET /config

Returns workspace configuration for the authenticated user, including available permissions, pre-chat form status, and active incident banners.

Example request:

curl "https://your-instance.useago.com/api/sdk/v1/config" \
  -H "X-User-Anon-Id: unique_user_id"

Example response:

{
  "object": "config",
  "permissions": [
    {
      "id": "p1q2r3s4-5678-90ab-cdef-1234567890ab",
      "name": "default",
      "display_name": "Default",
      "agents": [
        {
          "id": "e5f6a7b8-1234-5678-9abc-def012345678",
          "name": "Support Agent"
        }
      ],
      "ticket_form": null,
      "home_page": {
        "title": "How can we help?",
        "subtitle": "Ask anything about your account or our products.",
        "widget_starter": {
          "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
          "initial_message": "Hi! Anything I can look up for you?",
          "agent_id": null
        },
        "home_starters": [
          {
            "id": "b2c3d4e5-6789-01ab-cdef-234567890abc",
            "title": "Pricing",
            "description": "What does the Pro plan include?",
            "initial_message": "What does the Pro plan include?",
            "agent_id": null
          }
        ]
      },
      "file_attachments_enabled": true,
      "voice_enabled": false,
      "speech_to_text_enabled": false
    }
  ],
  "pre_chat_form_status": {
    "form_required": false,
    "form": null,
    "completed_today": false,
    "assigned_permission_id": null
  },
  "incident_info_banners": [],
  "proactive": { "enabled": false }
}

The home_page block carries what you configured for the widget home screen: the title and subtitle, the widget auto-starter (the first message the widget sends when it opens) and the conversation starter cards (home_starters). Each card gives the label to display (description, falling back to title) and the message to send when the card is clicked (initial_message), so a custom UI can send that message straight away without another request. Handle home_page as optional; an unconfigured home screen can contain null fields and an empty home_starters array. Cards and the auto-starter are already filtered to the agents this user can access.

The proactive block tells the SDK whether proactive mode is enabled for the workspace. When enabled is false, the SDK never shows a nudge and never calls the proactive endpoints.

Get Pre-Chat Form Status

GET /pre-chat-form/status

Check whether the pre-chat form is required for the current user before they can start a conversation.

Example request:

curl "https://your-instance.useago.com/api/sdk/v1/pre-chat-form/status" \
  -H "X-User-Anon-Id: unique_user_id"

Example response:

{
  "form_required": true,
  "form": {
    "enabled": true,
    "question_text": "What can we help you with?",
    "options": [
      {
        "id": "b1a2b3c4-5678-90ab-cdef-1234567890ab",
        "label": "I have a billing question",
        "permission_id": "f1a2b3c4-5678-90ab-cdef-1234567890ab",
        "permission_name": "billing",
        "permission_display_name": "Billing",
        "redirect_url": "",
        "order": 0
      },
      {
        "id": "b2a2b3c4-5678-90ab-cdef-1234567890ab",
        "label": "I need technical support",
        "permission_id": "f2a2b3c4-5678-90ab-cdef-1234567890ab",
        "permission_name": "support",
        "permission_display_name": "Support",
        "redirect_url": "",
        "order": 1
      }
    ]
  },
  "completed_today": false,
  "assigned_permission_id": null
}

Submit Pre-Chat Form

POST /pre-chat-form/submit

Submit the user’s pre-chat form selection. After a successful submission, the user is assigned a permission and can start conversations.

Request body:

Field	Type	Required	Description
option_id	string	Yes	The selected option ID from the form

Example request:

curl -X POST "https://your-instance.useago.com/api/sdk/v1/pre-chat-form/submit" \
  -H "X-User-Anon-Id: unique_user_id" \
  -H "Content-Type: application/json" \
  -d '{"option_id": "b1a2b3c4-5678-90ab-cdef-1234567890ab"}'

Example response:

{
  "success": true,
  "assigned_permission_id": "f1a2b3c4-5678-90ab-cdef-1234567890ab"
}

Get Active Incident Banners

GET /incident-info-banners/active

Returns any active incident or informational banners configured for the workspace.

Example request:

curl "https://your-instance.useago.com/api/sdk/v1/incident-info-banners/active" \
  -H "X-User-Anon-Id: unique_user_id"

Example response:

{
  "banners": [
    {
      "id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
      "title": "Scheduled Maintenance",
      "message": "We will perform scheduled maintenance on Saturday from 2:00 AM to 4:00 AM UTC.",
      "background_color": "#FFF3CD",
      "text_color": "#856404",
      "agent_ids": []
    }
  ]
}

When agent_ids is empty, the banner applies to all agents. When populated, it only appears for conversations with the listed agents.

---

Proactive Mode

Used by the SDK’s proactive mode. The evaluate endpoint requires proactive mode to be enabled for the workspace; the events endpoint accepts lifecycle reports regardless, so batches sent around a configuration change are not lost.

Evaluate an Intervention

POST /proactive/evaluate

Called by the SDK after a client-side trigger matched, when the trigger is configured with intervene: "agent". A fast model decides whether a nudge is worth showing right now and drafts its message.

Request body:

{
  "client_nudge_id": "d4f8a1b2-3c5e-4f6a-8b9c-0d1e2f3a4b5c",
  "trigger_id": "kyc-doc-stuck",
  "goal": "Help the user upload their KYC documents",
  "agent": "support",
  "signals": {
    "route": "/dossier/42",
    "idle_ms": 21000,
    "rage_clicks": 0,
    "route_bounces": 2,
    "field_errors": {},
    "recent_routes": ["/dossier/42", "/help"],
    "page_state": { "step": "documents", "uploaded": 0 }
  },
  "client_context": { "entries": {} },
  "client_functions": [
    {
      "name": "prefill_form",
      "description": "Prefill the KYC form",
      "parameters": { "type": "object", "properties": {} }
    }
  ]
}

client_nudge_id is a UUID generated by the SDK for this nudge instance; lifecycle events sent later reference it. agent (optional) is the agent id or name. signals includes counters, page paths, and any registered page_state. Page state is sent to the evaluation model without redaction, so include only values you intend to share with the assistant.

Example response:

{
  "object": "proactive_evaluation",
  "intervene": true,
  "message": "Need a hand with your documents?",
  "action": {
    "label": "Pre-fill for me",
    "function_name": "prefill_form",
    "arguments": { "step": "documents" }
  },
  "nudge_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

When intervene is false, message and action are null and the SDK stays silent. action is only ever one of the client_functions declared in the request.

Returns 403 (proactive_mode_disabled) when the feature is off for the workspace or the agent, and 429 (rate_limited) when the per-user evaluation cap is reached — the SDK treats both as “do not intervene”.

Report Nudge Events

POST /proactive/events

Batched lifecycle tracking for nudges, including static ones that never called the evaluate endpoint. Maximum 50 events per request.

Request body:

{
  "events": [
    {
      "client_nudge_id": "d4f8a1b2-3c5e-4f6a-8b9c-0d1e2f3a4b5c",
      "trigger_id": "kyc-doc-stuck",
      "source": "agent",
      "type": "shown",
      "message": "Need a hand with your documents?",
      "agent": "support",
      "occurred_at": "2026-07-09T10:30:00Z"
    }
  ]
}

source is "static" or "agent". type is one of shown, dismissed, accepted, converted. Events are idempotent per nudge and type: the first reported timestamp wins.

Example response:

{
  "object": "proactive_events",
  "recorded": 1
}

---

Error Format

SDK errors generally use this structure:

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "The requested resource was not found.",
    "param": null,
    "doc_url": "https://docs.useago.com/api/errors#not_found"
  }
}

Error Type	Status Codes	Description
authentication_error	401	Invalid or missing user identity
permission_error	403	The authenticated user does not have access to this resource
invalid_request_error	400, 404, 409, 413, 422	Invalid parameters, missing resources, conflicts, or oversized uploads
rate_limit_error	429	Too many requests
api_error	500, 503	Server failure or temporary transcription unavailability

Some ticket errors use a string-valued error and a top-level message instead. For example, creating a ticket on a disabled conversation as a non-staff user returns 410:

{
  "error": "conversation_disabled",
  "message": "conversation_disabled"
}

Clients should handle both formats: read error.message for an error object, or the top-level message or error string otherwise.

---

Related

• Public API v1 — the admin-facing REST API for managing your workspace
• API Key Authentication — how to generate and manage API keys
• SDK Integration — guide to embedding AGO in your application