---
title: "Quickstart"
method: GET
path: "/guides/quickstart"
tags: ["Quickstart"]
---

# Quickstart

`GET /guides/quickstart`

## Request

- Base URL: `https://developers.chatway.app/api/v1`
- URL: `https://developers.chatway.app/api/v1/guides/quickstart`
- Auth: none required

# 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:

```bash
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:

```json
{
  "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": "john@example.com",
      "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:

```bash
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](https://ngrok.com/). An inspection service such as [webhook.site](https://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:

| Code | Meaning |
|---|---|
| 200 | Request successful |
| 201 | Resource created successfully |
| 401 | Missing or invalid API key |
| 403 | Valid key, but API access not allowed for this account |
| 404 | Resource not found |
| 422 | Validation error (see `errors` object in the body) |
| 429 | Rate limit exceeded |

Example validation response:

```json
{
  "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

| Goal | Page |
|---|---|
| Try endpoints in the browser | **Testing the API** |
| Browse every endpoint and schema | **API Reference** |
| List pagination and sort order | **Pagination** |
| Error response bodies | **Errors** |
| Webhook signatures, retries, all events | **Webhook docs → Overview** |
| Get help from Chatway | **Customer support** |

## Response `200`

Documentation.

---

[API](https://skmtc.dev/chatway/apis/chatway-developer-docs.md) · [All operations](https://skmtc.dev/chatway/apis/chatway-developer-docs/llms.txt) · [OpenAPI document](https://skmtc.dev/chatway/apis/chatway-developer-docs/revisions/ca1a1da291cc?raw)