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. Every conversation starts here: create a session first, then send messages into it. The official SDKs do this for you.

Create a session​

POST /agent/session

Auth: required.

Body

FieldTypeRequiredDescription
userIdstringNoYour identifier for the end user, if known. On its own it does not attribute the session to a user — send a verified X-Appilots-User-Token for that. If you send both, they must match (403 otherwise).
deviceInfoobjectNoFree-form device metadata you want attached to the session.

Response — 201

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

sessionToken is the conversation's capability: send it as X-Appilots-Session-Token on every later request about this session — messages, continue, actions, escalations, pending actions, and ending it. It is returned only here and can't be fetched again, so store it together with sessionId. See Authentication → Conversation capabilities.

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, sessionToken } = data;

End a session​

DELETE /agent/session/:sessionId

Auth: API key + session token.

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..." \
  -H "X-Appilots-Session-Token: SESSION_TOKEN"

TypeScript

await fetch(`https://api.appilots.com/api/v1/agent/session/${sessionId}`, {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer ak_xxxxxxxxxxxx...',
    'X-Appilots-Session-Token': sessionToken,
  },
});

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: API key + session token.

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..." \
  -H "X-Appilots-Session-Token: SESSION_TOKEN"

TypeScript

const res = await fetch(
  `https://api.appilots.com/api/v1/agent/session/${sessionId}/pending-actions`,
  {
    headers: {
      Authorization: 'Bearer ak_xxxxxxxxxxxx...',
      'X-Appilots-Session-Token': sessionToken,
    },
  },
);
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