Quickstart

Get started with the Chatway API in just a few steps.

Chatway is a customer support and live chat platform that helps businesses communicate with website visitors, manage conversations, automate support with AI, and keep customer interactions in one place.

With the Chatway API, you can connect Chatway to your own apps, systems, and AI agents to access conversation data, manage contacts, send and reply to messages, and build custom workflows or integrations.

With webhooks, Chatway can automatically notify your system when important events happen, such as when a new message is received, so you can trigger automations, sync data, or connect Chatway with external services in real time.

The Chatway API and Webhooks are available on all plans, including the Free plan.

1. Create a Chatway account

To use the Chatway API, you first need a Chatway account.

If you don't have one yet, create an account and set up your Chatway workspace.

2. Generate an API key

In your Chatway dashboard, go to:

Settings → Developer Tools → API Keys

Give your API key a name, generate it, and copy it somewhere secure.

Your full API key is only shown once, so make sure to save it when it is created.

3. Authenticate your requests

Include your API key in the X-API-KEY header with every request:

X-API-KEY: your_api_key

Keep your API key private and never expose it in client-side code or public repositories.

Run these examples from your server or a trusted terminal. Keep the key in your environment's secret store. Replace example resource IDs with IDs returned for your own workspace; copying an example ID will not select your contact or conversation.

4. Send your first request

All API requests use the following base URL:

https://developers.chatway.app/api/v1

Confirm your key works with a simple read-only request:

curl -X GET "https://developers.chatway.app/api/v1/widgets" \
  -H "X-API-KEY: your_api_key" \
  -H "Accept: application/json"

If authentication is successful, Chatway returns 200 with JSON data.

5. Set up webhooks

Webhooks notify your application when something happens in Chatway, so you do not need to poll the API for new messages.

1. In your Chatway dashboard, go to Settings → Developer Tools → Webhooks.
2. Add an HTTPS endpoint URL that your server controls.
3. Copy the webhook secret when it is shown. You need it to verify signatures.
4. Subscribe to message.received (and any other events you need).

When an event occurs, Chatway sends an HTTP POST to your URL with a signed JSON envelope. Return any 2xx status within 4 seconds to acknowledge delivery.

For signature verification, retries, and header reference, see Webhook docs → Overview in the sidebar.

6. Receive a message and send a reply

This is the most common integration path: a visitor sends a chat message, your server receives a webhook, and you reply through the API.

Visitor message → message.received webhook → your server → POST /messages reply

Step A: Receive message.received

When a visitor sends a message, Chatway POSTs a payload like this:

{
  "id": "evt_1234567890abcdef1234567890abcdef",
  "event": "message.received",
  "data": {
    "message": {
      "id": "679f5ba4-3cbf-42eb-86dc-63566cec6b58",
      "content": "Hello, I need help",
      "attachments": [
        {
          "content": "https://cdn.example.com/files/invoice.pdf",
          "type": "file",
          "mime": "application/pdf",
          "original_file_name": "invoice.pdf",
          "size": 204800
        }
      ],
      "created_at": "2026-02-04T10:31:12Z"
    },
    "conversation": {
      "id": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab",
      "channel": "website",
      "status": "open",
      "widget_name": "Main site widget",
      "identifier": "eouqtiupanm6uvglwshy"
    },
    "visitor": {
      "id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1XXXXXXXXXX"
    }
  },
  "occurred_at": "2026-02-04T10:31:12Z",
  "version": "2026-09"
}

Verify the request signature before processing. See Webhook docs → Overview → Signature verification.

Step B: Extract the IDs you need

Save these IDs from the webhook:

• id identifies the event. Use it to recognize another delivery of the same event.
• data.conversation.id identifies the conversation. Pass it as conversation_id when replying with POST /messages.
• data.message.id identifies the incoming message. Keep it for logging and message-level references.
• data.visitor.id identifies the contact. Webhooks call this person a visitor; the REST API calls them a contact.

You do not need to call GET /conversations/all first if you already have data.conversation.id from the webhook.

Step C: Send the reply

Call POST /messages with the conversation ID from the webhook and the agent_id of the team member sending the reply (from GET /agents). Without agent_id, the message is saved as written by the visitor, not as an agent reply, and it fires message.received again:

curl -X POST "https://developers.chatway.app/api/v1/messages" \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab",
    "agent_id": "26fa75f2-7ac1-47b4-84e1-b943491ba4da",
    "content": "Thanks for reaching out! How can I help?"
  }'

A successful reply returns 201 with the created message. See API Reference → Messages → Create Message for all request fields.

Step D: Test locally before production

1. Expose your local webhook handler through an HTTPS tunnel, such as ngrok. An inspection service such as webhook.site can display deliveries, but does not run your local verification or reply code. Use synthetic messages when testing with an external inspection service.
2. Register it under Settings → Developer Tools → Webhooks and subscribe to message.received.
3. Send a test visitor message in your Chatway widget.
4. Confirm your endpoint receives the webhook and your POST /messages call returns 201.

See Testing the API for a full smoke-test checklist.

7. Handle errors and rate limits

Chatway uses standard HTTP status codes with JSON bodies. For example:

Example validation response:

{
  "message": "The limit must be an integer.",
  "errors": {
    "limit": [
      "The limit must be an integer."
    ]
  }
}

A 429 response means a rate limit was reached. See Rate limits for the current limits and how to retry.

See Errors and Rate limits in the sidebar for full response examples and retry guidance.

Install Chatway with an AI coding agent

Install Chatway on your website with an AI coding agent. Connect your Chatway account, retrieve its account-based JavaScript installation code through the API or MCP, and ask the agent to add the script to your website's global layout. The installation ID identifies your Chatway account and is not the widget ID used by conversation endpoints. Verify the website loads Chatway after deploying.

curl https://developers.chatway.app/api/v1/installation/code \
  -H "X-API-KEY: cw_your_api_key"

The response contains script_html, ready to paste:

{
  "data": {
    "installation_id": "AbCdEf123456",
    "script_url": "https://cdn.chatway.app/widget.js?id=AbCdEf123456",
    "script_html": "<script id=\"chatway\" async=\"true\" src=\"https://cdn.chatway.app/widget.js?id=AbCdEf123456\"></script>",
    "placement": "Add the script once to a shared layout that loads on every page. It can go inside <head> or <body>, preferably just before the closing </body> tag. For Shopify, Wix, WordPress and other supported platforms, you can use Chatway’s native app or plugin instead, or install the script directly. Chatway only returns the code; the coding agent installs it using its available tools and access.",
    "duplicate_check": "Before adding it, search the site for an existing <script id=\"chatway\"> ..."
  }
}

The coding agent edits your website's files. Chatway's API and MCP server only provide the code. Through MCP, the agent calls get-installation-code. After deploying, check the site with Get Installation Status.

What to read next