Widget API Reference

Core Concepts

Step-by-step Flow

1. Call GET /widget/config?site={site_key} on init to get your Pusher credentials and site settings. Your site_key is in the Chattr dashboard → Integrations → Custom Widget.
2. Generate visitor_uuid once per browser (UUID v4) and store it in a cookie (1-year expiry).
3. Call GET /widget/visitor-conversations to check if this visitor already has an open conversation.
4. If an open conversation exists: resume it — load messages, subscribe to Pusher.
5. If not: show your pre-chat UI (name/email fields or skip based on site config), then call POST /widget/conversations.
6. After creating or resuming, subscribe to the Pusher channel for real-time incoming messages.
7. Use GET /widget/conversations/{uuid}/messages as a polling fallback (5s offline, 15s when Pusher is connected).

1. Get Site Config

{
  "success": true,
  "data": {
    "site_key":          "your-site-uuid",
    "pusher_key":        "xxxxxxxxxxxxxxxx",
    "pusher_cluster":    "mt1",
    "pusher_host":       "soketi.chattr.ge",
    "pusher_port":       443,
    "pusher_tls":        true,
    "widget_color":      "#2D3FE0",
    "widget_position":   "bottom-right",
    "widget_vertical_offset": 22,
    "widget_button_style": "gradient",
    "welcome_message":   "Hello! How can we help you?",
    "pre_chat_enabled":  true,
    "pre_chat_ask_name":  true,
    "pre_chat_name_required": true,
    "pre_chat_ask_email": true,
    "pre_chat_email_required": false,
    "pre_chat_ask_phone": false,
    "pre_chat_phone_required": false,
    "show_typing":       true,
    "show_read_receipts": true
  },
  "message": null
}

2. List Visitor's Conversations

{
  "success": true,
  "data": [
    {
      "uuid": "conv-uuid-here",
      "status": "open",
      "created_at": "2025-05-24T10:00:00.000000Z",
      "last_message_at": "2025-05-24T10:05:00.000000Z",
      "preview": "Hi, I need help with my order…"
    }
  ],
  "message": null
}

3. Start a Conversation

// Request body example
{
  "site_key":      "your-site-uuid",
  "visitor_uuid":  "generated-visitor-uuid",
  "message":       "Hello, I need help!",
  "visitor_name":  "Jane Doe",
  "visitor_email": "jane@example.com",
  "visitor_page":  "https://yoursite.com/checkout",
  "visitor_meta":  {
    "id":        "12345",
    "fullName":  "Jane Doe",
    "company":   "Acme Corp",
    "phone":     "+1 555 000 0000",
    "planTier":  "enterprise",
    "accountId": "acc_9xkZ2",
    "region":    "us-east"
  }
}

{
  "success": true,
  "data": {
    "uuid": "conv-uuid-here",
    "conversation_id": 42,
    "messages": [
      {
        "id": 1,
        "conversation_id": 42,
        "sender_type": "visitor",
        "sender_id": null,
        "sender": null,
        "type": "text",
        "body": "Hello, I need help!",
        "attachment_path": null,
        "attachment_name": null,
        "attachment_size": null,
        "reactions": [],
        "is_read": false,
        "read_at": null,
        "edited_at": null,
        "created_at": "2025-05-24T10:00:00.000000Z"
      }
    ]
  },
  "message": null
}

4. Get Messages

{
  "success": true,
  "data": [
    {
      "id": 1,
      "conversation_id": 42,
      "sender_type": "visitor",
      "sender_id": null,
      "sender": null,
      "type": "text",
      "body": "Hello, I need help!",
      "attachment_path": null,
      "attachment_name": null,
      "attachment_size": null,
      "reactions": [],
      "is_read": false,
      "read_at": null,
      "edited_at": null,
      "created_at": "2025-05-24T10:00:00.000000Z"
    },
    {
      "id": 2,
      "conversation_id": 42,
      "sender_type": "operator",
      "sender_id": 7,
      "sender": { "id": 7, "name": "Support Agent", "avatar": null },
      "type": "text",
      "body": "Hi Jane, happy to help!",
      "attachment_path": null,
      "attachment_name": null,
      "attachment_size": null,
      "reactions": [{ "emoji": "👍", "operator_id": 7 }],
      "is_read": true,
      "read_at": "2025-05-24T10:01:30.000000Z",
      "edited_at": null,
      "created_at": "2025-05-24T10:01:00.000000Z"
    }
  ],
  "conversation_id": 42,
  "status": "open",
  "message": null
}

5. Send a Message

{ "body": "Can you help me with order #1234?" }

{
  "success": true,
  "data": {
    "id": 5,
    "type": "image",
    "body": "See this screenshot",
    "attachment_path": "https://chattr.ge/storage/attachments/42/screenshot.jpg",
    "attachment_name": "screenshot.jpg",
    "attachment_size": 204800,
    "sender_type": "visitor",
    "created_at": "2025-05-24T10:03:00.000000Z"
  },
  "message": null
}

6. Typing Indicator

{ "is_typing": true }

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

7. Rate a Conversation

{ "rating": 5, "comment": "Very helpful, thank you!" }

{ "success": true, "data": { "rating": 5 }, "message": "Thank you for your feedback!" }

8. Reopen a Resolved Conversation

{ "success": true, "data": { "status": "open" }, "message": null }

9. Preset Q&A Buttons

{
  "success": true,
  "data": [
    {
      "id": 1,
      "question_display": "What are your hours?",
      "answer": "We're available Monday–Friday, 9am–6pm GMT.",
      "trigger_keywords": ["hours", "open", "available"],
      "is_sticky": true
    }
  ],
  "message": null
}

Real-time via Pusher

Subscribe to the conversation channel after creating or resuming a conversation. Use Pusher.js (or any Pusher-compatible client library).

Setup

const pusher = new Pusher(PUSHER_KEY, {
  cluster: PUSHER_CLUSTER,  // e.g. "mt1"
  forceTLS: true
});

// conversationUuid = the `uuid` returned from POST /widget/conversations
// (the unguessable conversation identifier). The channel is keyed by uuid,
// never the numeric id, so it cannot be subscribed to by guessing ids.
const channel = pusher.subscribe(`conversation.${conversationUuid}`);

Event: MessageSent

Fires when any message is sent. The event payload has the same shape as a message object from GET /messages.

channel.bind('MessageSent', (data) => {
  // Skip internal operator notes
  if (data.type === 'note') return;

  // Deduplicate — you may have already added it optimistically
  const alreadyHave = messages.some(m => m.id && m.id === data.id);
  if (!alreadyHave) {
    messages.push(data);
    renderMessages();
  }
});

Event: OperatorTyping

channel.bind('OperatorTyping', ({ is_typing }) => {
  typingIndicator.hidden = !is_typing;
});

Session Management

Two cookies drive the session. Generate them client-side — no server interaction needed.

// Persistent visitor identity (1 per browser, 1-year expiry)
function getVisitorUuid() {
  let id = getCookie('chattr_uuid');
  if (!id) {
    id = crypto.randomUUID();
    setCookie('chattr_uuid', id, 365);
  }
  return id;
}

// Per-site conversation pointer (30-day expiry)
function getConvUuid(siteKey) {
  return getCookie(`chattr_conv_${siteKey}`);
}
function setConvUuid(siteKey, uuid) {
  setCookie(`chattr_conv_${siteKey}`, uuid, 30);
}

// Cookie helpers
function getCookie(name) {
  const m = document.cookie.match('(^|;) ?' + name + '=([^;]*)(;|$)');
  return m ? m[2] : null;
}
function setCookie(name, value, days) {
  const exp = new Date(Date.now() + days * 86400000).toUTCString();
  document.cookie = `${name}=${value};expires=${exp};path=/;SameSite=Lax`;
}

Pre-chat form logic

Read the site config to decide what to show before the first message:

Visitor identity pre-fill (skip pre-chat form)

If you already know the logged-in user (e.g. SaaS app), pass their data in visitor_meta and skip the form entirely:

startConversation(user.name, user.email, firstMessage, {
  id:       user.id,
  fullName: user.name,
  email:    user.email,
  company:  user.company,
});

Full Vanilla JS Example

A minimal working implementation covering the full flow (~70 lines).

const BASE    = 'https://chattr.ge';
const SITE    = 'your-site-key-uuid';
const VIS_ID  = getVisitorUuid();

let convUuid = null;
let messages = [];

async function init() {
  // 1. Check for existing conversations
  const r = await fetch(`${BASE}/widget/visitor-conversations?visitor_uuid=${VIS_ID}&site_key=${SITE}`);
  const { data: convs } = await r.json();
  const active = convs.find(c => c.status !== 'resolved');

  if (active) {
    convUuid = active.uuid;
    await loadMessages(); // loads messages + subscribes Pusher
  } else {
    showPreChatForm();
  }
}

async function startConversation(name, email, firstMessage, meta = null) {
  const r = await fetch(`${BASE}/widget/conversations`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      site_key:      SITE,
      visitor_uuid:  VIS_ID,
      visitor_name:  name,
      visitor_email: email,
      message:       firstMessage,
      visitor_page:  location.href,
      visitor_meta:  meta,
    }),
  });
  const { data } = await r.json();
  convUuid = data.uuid;
  setConvUuid(SITE, convUuid);
  messages = data.messages;
  subscribeRealtime(data.conversation_id);
  renderMessages();
}

async function sendMessage(text) {
  const r = await fetch(`${BASE}/widget/conversations/${convUuid}/messages`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ body: text }),
  });
  const { data: msg } = await r.json();
  messages.push(msg);
  renderMessages();
}

async function loadMessages() {
  const r = await fetch(`${BASE}/widget/conversations/${convUuid}/messages`);
  const res = await r.json();
  messages = res.data;
  subscribeRealtime(convUuid);
  renderMessages();
  if (res.status === 'resolved') showReopenBar();
}

function subscribeRealtime(conversationUuid) {
  const pusher = new Pusher(PUSHER_KEY, { cluster: PUSHER_CLUSTER, forceTLS: true });
  const ch = pusher.subscribe(`conversation.${conversationUuid}`);

  ch.bind('MessageSent', (msg) => {
    if (msg.type === 'note') return;
    if (messages.some(m => m.id === msg.id)) return; // deduplicate
    messages.push(msg);
    renderMessages();
    playNotificationSound();
  });

  ch.bind('OperatorTyping', ({ is_typing }) => {
    document.getElementById('typing-indicator').hidden = !is_typing;
  });

  // Slow poll as fallback
  setInterval(() => {
    if (convUuid) loadMessages();
  }, ch.connection?.state === 'connected' ? 15000 : 5000);
}

function sendTypingIndicator(isTyping) {
  if (!convUuid) return;
  fetch(`${BASE}/widget/conversations/${convUuid}/typing`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ is_typing: isTyping }),
  });
}

init();

Errors & Rate Limits

All endpoints return a consistent shape on error:

{
  "success": false,
  "data": null,
  "message": "Error description"
}

Per-endpoint rate limits