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.

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.

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 the timeout 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",
  "occurred_at": "2026-02-04T10:31:12Z",
  "version": "1.0",
  "data": {
    "message": {
      "id": "msg_789",
      "content": "Hello, I need help",
      "attachments": [],
      "created_at": "2026-02-04T10:31:12Z"
    },
    "conversation": {
      "id": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab",
      "channel": "website",
      "status": "open",
      "widget_name": "Main site widget",
      "identifier": "wdg_abc123"
    },
    "visitor": {
      "id": "vis_456",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": null
    }
  }
}

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

Step B: Extract the IDs you need

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:

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",
    "content": "Thanks for reaching out! How can I help?"
  }'

To send the reply as a specific team member, include agent_id from GET /agents:

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 a temporary HTTPS URL (for example ngrok or webhook.site).
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."
    ]
  }
}

The API allows 60 requests per minute per API key. A 429 response includes a Retry-After header when available.

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

What to read next