Getting Started

Getting Started#

The Conversations API lets you drive Gydr-powered chat from your own backend or channel. Use it to add AI chat to a mobile app, build a WhatsApp or Messenger bridge, power an internal support tool, or connect any channel that cannot embed the widget SDK.

All calls go to the same REST endpoint your backend controls. You create a session, send messages on behalf of your visitor, and receive the AI response synchronously or via a callback URL.

Prerequisites#

Before making your first call you need:

• An API key with the conversations:chat scope. Create one in Console → Settings → Developer. See Authentication for how API keys work and which scopes are available.
• The Widget ID of the chatbot you want to use. Find it in Console → Widgets → select a widget → the ID is shown at the top of the settings panel.

Base URL#

All Conversations API endpoints share the same base URL:

Pass your API key in the X-API-Key header on every request. All request and response bodies are JSON.

Step 1 — Create a Session#

Call POST /widgets/{widgetId}/conversations to open a new conversation. Supply a visitorId that maps the session to a user in your system. The server returns a sessionId you will use for every subsequent call in this conversation.

curl -X POST https://api.infinichat.dev/widgets/{widgetId}/conversations \
  -H "X-API-Key: api_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "visitorId": "user_12345",
    "visitorContext": {
      "name": "Sarah",
      "email": "sarah@example.com"
    },
    "language": "en",
    "timezone": "America/New_York"
  }'

A successful call returns 201 Created:

{
  "data": {
    "sessionId": "sess_dBLPP9tYcVKrzrxC5_gTR",
    "widgetId": "6751a3e...",
    "visitorId": "user_12345",
    "status": "active",
    "createdAt": "2026-03-23T14:00:00.000Z",
    "resumed": false
  },
  "meta": { "creditsConsumed": 1 }
}

If you pass a sessionId that already exists and is still active, the API returns 200 with resumed: true and preserves the existing conversation history. This is useful for reconnect scenarios.

Step 2 — Send a Message#

Send the visitor's first message to POST /widgets/{widgetId}/conversations/{sessionId}/messages. The default response_type is sync, which waits for the AI and returns the answer in the same HTTP response.

curl -X POST https://api.infinichat.dev/widgets/{widgetId}/conversations/{sessionId}/messages \
  -H "X-API-Key: api_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What are your business hours?",
    "response_type": "sync"
  }'

Response:

{
  "data": {
    "messageId": "msg_abc123",
    "content": "We're open Monday to Friday, 9 am to 6 pm Eastern Time.",
    "products": [],
    "actions": [],
    "sessionEnded": false,
    "credits": {
      "chat": 6,
      "retrieval": 2,
      "orchestration": 1,
      "embedding": 0,
      "rerank": 1,
      "plugin": 0,
      "crawler": 0
    },
    "usage": { "inputTokens": 820, "outputTokens": 18 }
  },
  "meta": { "creditsConsumed": 12 }
}

The content field holds the AI's reply. The credits object itemises metered usage across seven fixed keys, and meta.creditsConsumed gives the turn total. When sessionEnded is true, the AI resolved the session automatically — no further messages can be sent.

Step 3 — Continue the Conversation#

Keep using the same sessionId for every follow-up message. The API maintains conversation history so the AI has context from earlier turns.

curl -X POST https://api.infinichat.dev/widgets/{widgetId}/conversations/{sessionId}/messages \
  -H "X-API-Key: api_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Are you open on public holidays?",
    "response_type": "sync"
  }'

There is no explicit "send history" step — the session stores each message and the AI reads the thread automatically. Send as many follow-up messages as needed.

Sync vs Callback Mode#

The examples above use response_type: "sync", which waits up to approximately 25 seconds for the AI and returns the answer inline. For queries that may trigger multiple tool calls — such as a complex knowledge-base lookup or an external plugin — you can switch to response_type: "callback". The API returns 202 Accepted immediately and POSTs the AI response to a callback URL you configure on the API key. Callback mode requires a callback URL to be set when the key is created; using it without one returns a 400 error. For full details, request fields, and callback signature verification, see Sessions & Messages.

Next Steps#

• Sessions & Messages — full request and response field reference, callback mode setup, form submissions, rating a session, and retrieving message history.
• Response Formats — configure the reply format per API key: Markdown, plain text, Facebook Messenger, or WhatsApp Business.
• Webhooks — receive events for session lifecycle changes alongside or instead of callback mode.