Pallio AI — Knowledge Base Chat#

You can chat with a Pallio AI persona — an AI assistant backed by a curated knowledge base of uploaded documents. The persona answers questions using RAG (Retrieval-Augmented Generation) with document citations.

Setup#

The user must set the PALLIO_PERSONA_ID environment variable to the ID of a public Pallio persona. Browse available personas at https://pallioai.com/community.

How to Use#

Step 1: Initialize a Session#

Before sending any messages, initialize a session to get an authentication token.

bash

curl -s "https://pallioai.com/api/widget/init/$PALLIO_PERSONA_ID"

The response contains:

• token — Session token (valid for 2 hours). Store this for all subsequent messages.
• persona.name — The persona's display name.
• persona.welcomeMessage — An introductory message from the persona. Show this to the user.
• persona.starterPrompts — Suggested first questions. Offer these to the user.
• persona.messageLimit — Maximum free messages per session (typically 3).

Step 2: Send Messages#

Send the user's message with the session token. Maintain conversation history for context.

bash

curl -s -X POST "https://pallioai.com/api/widget/chat" \
  -H "X-Widget-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What topics do you cover?",
    "history": []
  }'

The history array should contain all previous messages in the conversation:

json

[
  { "role": "user", "content": "What topics do you cover?" },
  { "role": "assistant", "content": "I cover fire safety procedures..." },
  { "role": "user", "content": "Tell me more about ventilation." }
]

The response contains:

• response — The AI-generated answer. Display this to the user.
• sources — Array of { title, page } objects. Display these as citations below the response.
• messageNumber — Which message this is (1, 2, 3...).
• messagesRemaining — How many free messages remain.
• nudge — If "signup_soft", gently suggest signing up. If "signup_required", the session is exhausted.
• signupUrl — URL for the user to create a full Pallio account.

Step 3: Display Sources#

When sources is present and non-empty, format citations below the response:

text

Sources:
- Document Name (p. 42)
- Another Document (p. 15)

Step 4: Handle the Message Limit#

Each session allows a limited number of free messages (typically 3).

• When messagesRemaining reaches 0 or nudge is "signup_required", inform the user: "You've used all free messages for this session. Sign up for full access: {signupUrl}"
• To start a new session, call the init endpoint again (rate limited to 30/hour).

For unlimited access, the user can get a Pallio API key (Professional tier or higher) — see https://pallioai.com/settings.

Error Handling#

Error CodeMeaningActionSESSION_NOT_FOUNDToken is invalidRe-initialize the sessionSESSION_EXPIREDToken TTL exceeded (2 hours)Re-initialize the sessionMESSAGE_LIMIT_REACHEDFree messages exhaustedShow signup URLRATE_LIMITEDToo many requestsWait and retry (check retryAfter field)PERSONA_NOT_FOUNDInvalid persona IDVerify PALLIO_PERSONA_ID is correctWIDGET_DISABLEDPersona owner disabled widgetTry a different persona

Important Notes#

• Sessions expire after 2 hours. If you get SESSION_EXPIRED, initialize a new session.
• Rate limits: 30 session inits per IP per hour, 10 messages per IP per hour.
• The persona only answers from its uploaded knowledge base — it will not fabricate answers.
• This is the free widget endpoint. For full RAG pipeline access (hybrid search, more tokens, higher limits), use the Pallio Agent API with an API key.