Skip to main content

Agent Sessions

A session scopes one conversation between an end user and the agent. See Sessions & Users for the underlying concept. Most integrators let POST /agent/message create a session implicitly on first use, but you can also manage sessions explicitly with the routes below.

Create a session​

POST /agent/session

Auth: required.

Body

FieldTypeRequiredDescription
userIdstringNoYour identifier for the end user, if known.
deviceInfoobjectNoFree-form device metadata you want attached to the session.

Response — 201

{
  "success": true,
  "data": { "sessionId": "..." }
}

curl

curl https://api.appilots.com/api/v1/agent/session \
  -X POST \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_123"}'

TypeScript

const res = await fetch("https://api.appilots.com/api/v1/agent/session", {
  method: "POST",
  headers: {
    Authorization: "Bearer ak_xxxxxxxxxxxx...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ userId: "user_123" }),
});
const { data } = await res.json();
const sessionId = data.sessionId;

End a session​

DELETE /agent/session/:sessionId

Auth: required.

Response — 200

{
  "success": true,
  "data": { "message": "..." }
}

curl

curl https://api.appilots.com/api/v1/agent/session/SESSION_ID \
  -X DELETE \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..."

TypeScript

await fetch(`https://api.appilots.com/api/v1/agent/session/${sessionId}`, {
  method: "DELETE",
  headers: { Authorization: "Bearer ak_xxxxxxxxxxxx..." },
});

Recover pending actions​

GET /agent/session/:sessionId/pending-actions

Returns actions the server persisted but that your client hasn't reported completion for yet — useful for recovering state after a dropped connection (e.g. mid-stream during /agent/message/stream).

Auth: required.

Response — 200

{
  "success": true,
  "data": {
    "actions": [
      { "id": "...", "type": "navigate", "payload": { ... }, "messageId": "..." }
    ]
  }
}

An internal error fetching pending actions returns error.code: "RECOVER_PENDING_FAILED" with a 500 status.

curl

curl "https://api.appilots.com/api/v1/agent/session/SESSION_ID/pending-actions" \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..."

TypeScript

const res = await fetch(
  `https://api.appilots.com/api/v1/agent/session/${sessionId}/pending-actions`,
  { headers: { Authorization: "Bearer ak_xxxxxxxxxxxx..." } }
);
const { data } = await res.json();
GET /agent/popular-prompts?screen=<name>&limit=<n>

Returns suggested prompts to show users — a mix of ones you've defined for a screen, ones popular on that screen across your users, and ones popular globally.

Auth: required.

Query parameters

ParamTypeRequiredDescription
screenstringNoScreen name to scope screen-level suggestions to.
limitnumberNoMax items per list.

Response — 200

{
  "success": true,
  "data": {
    "devDefined": ["..."],
    "screenPopular": ["..."],
    "globalPopular": ["..."],
    "computedAt": "2026-01-01T00:00:00.000Z"
  }
}

curl

curl "https://api.appilots.com/api/v1/agent/popular-prompts?screen=Home&limit=5" \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..."

TypeScript

const res = await fetch(
  "https://api.appilots.com/api/v1/agent/popular-prompts?screen=Home&limit=5",
  { headers: { Authorization: "Bearer ak_xxxxxxxxxxxx..." } }
);
const { data } = await res.json();

Personalization​

GET /agent/personalization

Returns the project's dashboard-configured personalization — theme tokens, branding strings, FAB color/image, default locale. The SDK calls this once on AppilotsProvider mount and applies the values as fallbacks for props the app didn't set in code; you'd call it directly only when building a fully custom chat UI. The project is derived from the API key, so there are no parameters.

The response is served from a server-side cache (1h TTL) that is invalidated whenever the personalization is saved in the dashboard. personaPrompt is intentionally not included — it is composed into the system prompt server-side and never ships to clients. null means "not configured": fall through to your own defaults.

Auth: required.

Response — 200

{
  "success": true,
  "data": {
    "assistantName": "Aria",
    "assistantAvatar": null,
    "emptyStateIcon": "🤖",
    "welcomeMessage": null,
    "chatTitle": "Suporte Acme",
    "poweredByVisible": true,
    "theme": { "colors": { "primary": "#0070f3" }, "mode": "auto" },
    "defaultLocale": "pt-BR",
    "triggerButtonColor": null,
    "triggerButtonImageUrl": null
  }
}

curl

curl "https://api.appilots.com/api/v1/agent/personalization" \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..."

TypeScript

const res = await fetch(
  "https://api.appilots.com/api/v1/agent/personalization",
  { headers: { Authorization: "Bearer ak_xxxxxxxxxxxx..." } }
);
const { data } = await res.json();
Last updated on