> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatsyncs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> How to authenticate and make requests to the ChatSyncs Developer API — base URL, the apiToken parameter, GET vs POST support, and the {status, message} response shape every endpoint returns. Use when a developer asks how to get their API key, what URL to call, or how to read a ChatSyncs API response.

The ChatSyncs Developer API lets you send WhatsApp messages, manage subscribers, labels, and
catalogs, and trigger bot flows directly from your own server — everything you can do by hand
in ChatSyncs, also available over HTTP.

<Tip>
  New here? Jump to the [Quickstart](#quickstart) below for a copy-paste walkthrough of your
  first API call, step by step.
</Tip>

## Get your API key

Every request needs an **API key**. Find yours under **Control Panel → Developer** — it's
shown at the top of that page as `Your API key`.

<Warning>
  **Treat your API key like a password.** Anyone with it can send messages and read subscriber
  data on your account. Never commit it to a public repository or share it in a support ticket —
  if you think it's leaked, regenerate it from the same Developer page.
</Warning>

## Base URL

```
https://platform.chatsyncs.com/api/v1
```

Every endpoint path in this reference is relative to this base URL, e.g. `/whatsapp/send`
means `https://platform.chatsyncs.com/api/v1/whatsapp/send`.

## Authentication

Pass your API key as the `apiToken` parameter on every request — either as a query parameter
(GET) or a form field (POST):

```bash theme={null}
curl "https://platform.chatsyncs.com/api/v1/whatsapp/send?apiToken=YOUR_API_KEY&..."
```

A few endpoints (like **Upload Media**) also accept it as a Bearer token instead:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.chatsyncs.com/api/v1/whatsapp/upload/media"
```

## Making requests

Most endpoints accept **both GET and POST** — send parameters as a query string on GET, or as
form fields (`-d` with curl) on POST. A few write-heavy or file-upload endpoints are
**POST-only**; each endpoint page says which methods it supports.

<Info>
  For GET requests, URL-encode any parameter that contains spaces or special characters (e.g. a
  text `message`).
</Info>

<Note>
  **There's no official ChatSyncs SDK package yet.** The code samples on each endpoint page
  (cURL, Node.js, Python, PHP) are plain HTTP calls using each language's standard library —
  `fetch`, `requests`, and `curl`/`file_get_contents` — not calls into a published package.
</Note>

### Quickstart

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://platform.chatsyncs.com/api/v1/whatsapp/send' \
    -d 'apiToken=YOUR_API_KEY' \
    -d 'phone_number_id=YOUR_PHONE_NUMBER_ID' \
    -d 'phone_number=919999999999' \
    -d 'message=Hello from the ChatSyncs API!'
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    apiToken: "YOUR_API_KEY",
    phone_number_id: "YOUR_PHONE_NUMBER_ID",
    phone_number: "919999999999",
    message: "Hello from the ChatSyncs API!",
  });

  const res = await fetch("https://platform.chatsyncs.com/api/v1/whatsapp/send", {
    method: "POST",
    body: params,
  });

  console.log(await res.json());
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://platform.chatsyncs.com/api/v1/whatsapp/send",
      data={
          "apiToken": "YOUR_API_KEY",
          "phone_number_id": "YOUR_PHONE_NUMBER_ID",
          "phone_number": "919999999999",
          "message": "Hello from the ChatSyncs API!",
      },
  )

  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://platform.chatsyncs.com/api/v1/whatsapp/send');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, [
      'apiToken' => 'YOUR_API_KEY',
      'phone_number_id' => 'YOUR_PHONE_NUMBER_ID',
      'phone_number' => '919999999999',
      'message' => 'Hello from the ChatSyncs API!',
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = json_decode(curl_exec($ch), true);
  curl_close($ch);

  print_r($response);
  ```
</CodeGroup>

Almost every endpoint also requires a **`phone_number_id`** — this identifies which of your
connected WhatsApp numbers (bots) the request acts on. Find it under **Chatbot Manager → (your
bot) → Change Settings**. That same panel also shows **`whatsapp_bot_id`**, needed by a few
endpoints like [Get Delivery Message Status](/developer-api/whatsapp/get-message-status).

## Request flow

```mermaid theme={null}
sequenceDiagram
    participant Your Server
    participant ChatSyncs API
    participant WhatsApp

    Your Server->>ChatSyncs API: POST /whatsapp/send (apiToken, phone_number_id, message, phone_number)
    ChatSyncs API->>WhatsApp: Deliver message
    ChatSyncs API-->>Your Server: {status, wa_message_id, message}
    Your Server->>ChatSyncs API: GET /whatsapp/get/message-status (wa_message_id)
    ChatSyncs API-->>Your Server: {status: delivered/read/failed}
```

## Reading the response

Every response is JSON with a **`status`** field:

* **`"status": "1"`** (or `true` on a few endpoints) — the request succeeded. A `message` field
  usually confirms what happened, or returns the requested data (a subscriber, a list, etc.).
* **`"status": "0"`** (or `false`) — the request failed. `message` explains why, e.g.
  `"WhatsApp account not found."` or `"Subscriber limit has been exceeded."`

```json theme={null}
{"status":"1","message":"Message sent successfully."}
```

```json theme={null}
{"status":"0","message":"WhatsApp account not found."}
```

<Warning>
  **Always check `status` before trusting the response** — some failure responses still return
  an HTTP 200, so a successful HTTP request doesn't guarantee the action succeeded.
</Warning>

## Pagination

List endpoints (Subscriber List, Get Conversation) accept **`limit`** (how many records to
return) and **`offset`** (how many to skip) to page through results — see the worked
page-by-page example on [Subscriber List](/developer-api/subscriber/list-subscribers#pagination-and-ordering).

## Frequently asked

<AccordionGroup>
  <Accordion title="Where do I get my API key?">
    Go to **Control Panel → Developer** in ChatSyncs — your key is shown at the top of that
    page.
  </Accordion>

  <Accordion title="Do I send my API key as a header or a parameter?">
    As the `apiToken` parameter (query string on GET, form field on POST) for almost every
    endpoint. A few endpoints, like Upload Media, also accept `Authorization: Bearer
            YOUR_API_KEY`.
  </Accordion>

  <Accordion title="How do I know if my request actually worked?">
    Check the `status` field in the JSON response — `"1"` (or `true`) means success, `"0"` (or
    `false`) means failure, with a `message` explaining what went wrong.
  </Accordion>

  <Accordion title="What is phone_number_id and where do I find it?">
    It identifies which connected WhatsApp number/bot the request applies to. You'll find it in
    **Chatbot Manager** for that bot.
  </Accordion>
</AccordionGroup>