For developers

Open API

Send and receive private direct messages, post statuses, and integrate the community into your own apps. Authenticate with a personal API token, then POST JSON to the gateway endpoint.

Sign in to enable API access

You need an account to enable API integration and generate a token. Sign in or create a free account to continue.

Reference

POST

Endpoint

All actions are sent as a JSON POST to this single gateway URL (no trailing slash).

POST https://yidchats.com/functions/apiGateway

POST

Authentication

Send your API token as a Bearer token in the Authorization header. Enable integration on your account and create a token above.

Authorization: Bearer YOUR_API_TOKEN

POST

Request format

The body is a JSON object with an action field and the action's parameters.

curl -X POST https://yidchats.com/functions/apiGateway \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"sendDirectMessage","recipient":"member@example.com","message":"Hello from the API!"}'

Actions

POSTsendDirectMessage

Send a direct message to another member. Provide an existing thread_id, or a recipient (email or @username), or a number (WhatsApp number) to start or continue a 1:1 chat. You can send text, an image, or a file attachment.

Parameters

thread_id — existing conversation id (or use recipient/number)
recipient — email or @username of the member to message (or use thread_id/number)
number — WhatsApp number of the member to message (or use thread_id/recipient)
message — text body (required unless an attachment is present)
image_url — optional image attachment URL
file_url — optional file attachment URL
file_name — optional file name for file attachments

Example

{
  "action": "sendDirectMessage",
  "number": "18862838882",
  "message": "Hi there!",
  "image_url": "https://example.com/photo.jpg"
}

POSTlookupNumber

Check whether a WhatsApp number belongs to a member on this system. Returns whether the number exists and, if so, the member's username and display name so you can message them.

Parameters

number — required — the WhatsApp number to look up

Example

{
  "action": "lookupNumber",
  "number": "18862838882"
}

POSTgetDirectMessages

Fetch the most recent messages from one of your direct message conversations.

Parameters

thread_id — required — the conversation to read
limit — optional — number of messages (max 200, default 50)

Example

{
  "action": "getDirectMessages",
  "thread_id": "THREAD_ID",
  "limit": 20
}

POSTpostStatus

Post a status (text or photo) visible to your mutual contacts.

Parameters

caption — text content (required unless image_url is present)
image_url — optional photo URL
bg_color — optional background color for text statuses (default #25D366)
text_color — optional text color for text statuses (default #ffffff)

Example

{
  "action": "postStatus",
  "caption": "Building something new 🚀"
}

Webhooks

Set a webhook URL in the Your API access panel above to receive new direct messages in real time. Whenever a new message is sent in a direct message conversation you're a participant of, the platform POSTs a JSON payload to your URL.

The request body looks like:

{
  "event": "dm_message",
  "message": {
    "id": "MSG_ID",
    "message": "Hello!",
    "author_name": "Solomon",
    "author_email": "member@example.com",
    "image_url": null,
    "file_url": null,
    "file_name": null,
    "audio_url": null,
    "created_date": "2026-09-10T18:00:00Z"
  },
  "thread": { "id": "THREAD_ID" },
  "site": "WhatsApp Groups"
}

event is dm_message for direct messages, with the thread field holding the conversation id. Your endpoint should respond with a 2xx status; delivery is best-effort and times out after 10 seconds.

Responses

Successful calls return { "ok": true, ... } with a 200 status. Errors return a JSON error field with an appropriate HTTP status (401 invalid token, 403 forbidden, 404 not found, 400 bad request).