---
title: "WhatsApp API endpoints: the reference you can hold in your head"
description: "The WAME WhatsApp API uses https://us.api-wa.me with the pattern /{key}/... where {key} is your instance key and doubles as authentication — no auth header. Endpoints group into instance, messages, groups, contacts and webhooks. Full list with curl examples."
url: "https://api-wa.me/blog/whatsapp-api-endpoints"
language: "pt-BR"
og:type: "article"
published_time: "2026-09-12"
modified_time: "2026-09-12"
author: "Raphael Serafim"
keywords: "whatsapp api endpoints, whatsapp api documentation, whatsapp api reference, whatsapp api curl, send whatsapp message api, whatsapp api base url"
reading_time: "6 min read"
---

# WhatsApp API endpoints: the reference you can hold in your head

> The WAME WhatsApp API uses https://us.api-wa.me with the pattern /{key}/... where {key} is your instance key and doubles as authentication — no auth header. Endpoints group into instance, messages, groups, contacts and webhooks. Full list with curl examples.

**Base URL `https://us.api-wa.me`, pattern `/{key}/...`, where `{key}` is your instance key and also your authentication — there is no auth header to set.** From there the surface splits into five groups: instance, messages, groups, contacts and webhooks.

That is genuinely the whole mental model. This page lists the routes so you can skim them in one sitting; the exhaustive parameter-by-parameter reference lives in [/docs](/docs).

## Ground rules

- **Base URL:** `https://us.api-wa.me`
- **Auth:** the instance `key` sits in the path — `https://us.api-wa.me/YOUR_KEY/...`. No header.
- **Format:** JSON request bodies; phone numbers in international format, digits only.

Because the key *is* the credential, the full URL is a secret. Keep it server-side, out of logs, and out of screenshots.

## Instance and connection

| Method | Endpoint | What it does |
| --- | --- | --- |
| `GET` | `/{key}/instance` | Connection status and QR code |
| `POST` | `/{key}/instance` | Connect (generates the QR code) |
| `POST` | `/{key}/instance/pairing-code` | Connect by pairing code instead |
| `PUT` | `/{key}/instance` | Configure webhooks |
| `PATCH` | `/{key}/instance` | Settings: auto-read, store media, and so on |
| `DELETE` | `/{key}/instance` | Disconnect (logout) |

## Sending messages

| Method | Endpoint | Type |
| --- | --- | --- |
| `POST` | `/{key}/message/text` | Text |
| `POST` | `/{key}/message/image` | Image |
| `POST` | `/{key}/message/video` | Video |
| `POST` | `/{key}/message/audio` | Audio |
| `POST` | `/{key}/message/document` | Document |
| `POST` | `/{key}/message/location` | Location |
| `POST` | `/{key}/message/contact` | Contact card |
| `POST` | `/{key}/message/button_reply` | Quick reply buttons |
| `POST` | `/{key}/message/button_action` | Action buttons (open URL / call / copy code) |
| `POST` | `/{key}/message/list` | List menu |
| `POST` | `/{key}/message/pix` | Pix payment (Brazil) |

The smallest thing that works:

```bash
curl -X POST "https://us.api-wa.me/YOUR_KEY/message/text" \
  -H "Content-Type: application/json" \
  -d '{ "to": "14155550132", "text": "Hello!" }'
```

## Groups and contacts

| Method | Endpoint | What it does |
| --- | --- | --- |
| `GET` | `/{key}/groups` | List groups |
| `POST` | `/{key}/groups` | Create a group |
| `POST` | `/{key}/groups/{id}/participants` | Add participants |
| `GET` | `/{key}/contacts` | List contacts |
| `GET` | `/{key}/contacts/{number}` | Contact profile |
| `GET` | `/{key}/actions/registered` | Check whether a number is on WhatsApp |

That last one is worth a note: checking registration before a send is the cheapest way to keep a list clean, and on the official API it is the difference between a delivered template and one you paid for that went nowhere.

## Webhooks: receiving events

Incoming messages arrive by webhook. Register them with `PUT /{key}/instance`:

```bash
curl -X PUT "https://us.api-wa.me/YOUR_KEY/instance" \
  -H "Content-Type: application/json" \
  -d '{
    "allowWebhook": true,
    "allowNumber": "all",
    "webhookMessage": "https://your-site.com/webhook",
    "webhookConnection": "https://your-site.com/webhook"
  }'
```

You can point each event type at a **different URL** — messages, connection changes, QR code, groups, your own outbound messages, history — and restrict which numbers fire them with `allowNumber`. Separate URLs are worth using: connection events and message events have very different failure modes, and mixing them into one handler is how a reconnect storm ends up in the same retry queue as customer replies.

## Let an assistant do the integration

Two things make this API unusually easy to hand to a model:

- **Every page has a Markdown twin.** Append `.md` to any URL on this site — [this page](/blog/whatsapp-api-endpoints.md), the docs, anything — and you get clean Markdown instead of HTML.
- **There is an `llms.txt`** carrying the whole API surface in a form written for language models. Paste it into Claude, ChatGPT or Cursor and the assistant already knows every endpoint and parameter.

If you would rather the agent call the API itself instead of writing code for you, there is a hosted MCP server: see [WhatsApp MCP server](/blog/whatsapp-mcp-server).

## Next

- [Full documentation](/docs) — every endpoint, every parameter
- [WhatsApp API pricing](/blog/whatsapp-api-pricing) — what Meta bills, and what is free
- [Official vs unofficial API](/blog/official-vs-unofficial-whatsapp-api) — which one these endpoints should run on

## Perguntas frequentes

### What is the base URL of the WAME WhatsApp API?

https://us.api-wa.me. Every endpoint follows the pattern https://us.api-wa.me/{key}/... where {key} is your instance key.

### How does authentication work?

The instance key goes in the URL path itself, as /{key}/.... There is no authentication header to set. Because the key is the credential, treat the full URL as a secret: keep it out of client-side code, logs and screenshots.

### What are the main endpoint groups?

Five. Instance and connection at /{key}/instance; message sending at /{key}/message/text, /image, /button_action, /list and others; groups at /{key}/groups; contacts at /{key}/contacts; and webhook configuration through PUT /{key}/instance.

### How do I send my first message?

One POST. curl -X POST https://us.api-wa.me/YOUR_KEY/message/text -H 'Content-Type: application/json' -d '{"to": "14155550132", "text": "Hello!"}'. The number goes in international format, digits only.

### How do I receive incoming messages?

Configure webhooks with PUT /{key}/instance, setting allowWebhook to true and pointing webhookMessage at your HTTPS endpoint. You can register separate URLs per event type — messages, connection, QR code, groups, your own outbound messages, history — and filter which numbers trigger them with allowNumber.

### Is there a machine-readable reference for AI assistants?

Yes. Every page of the site is available as Markdown by appending .md to its URL, and there is an llms.txt context file with the full API surface written for language models. Paste it into Claude, ChatGPT or Cursor and the assistant already knows every endpoint and parameter.