Guides

Send Your First Message

Prerequisites

  • A Muchaw DEV account with an API key
  • A WhatsApp number with status: ACTIVE (see Quickstart)
  • The recipient’s phone number must have WhatsApp installed

Step 1 — Find your number ID

$curl "https://dev.muchau.com.br/api/numbers?status=ACTIVE" \
>  -H "Authorization: Bearer $MUCHAW_API_KEY"

Copy the id of the number you want to send from.

Step 2 — Send a text message

$curl -X POST https://dev.muchau.com.br/api/messages/send \
>  -H "Authorization: Bearer $MUCHAW_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "number_id": "<YOUR_NUMBER_ID>",
>    "to": "5511999990000",
>    "type": "text",
>    "text": { "body": "Hello! Your order #1234 is ready." }
>  }'

Successful response:

1{
2  "id": "msg_01j...",
3  "wa_message_id": "wamid.HBgL...",
4  "status": "sent"
5}

Step 3 — Prevent duplicate sends (optional)

Add the Idempotency-Key header to safely retry failed requests:

$curl -X POST https://dev.muchau.com.br/api/messages/send \
>  -H "Authorization: Bearer $MUCHAW_API_KEY" \
>  -H "Content-Type: application/json" \
>  -H "Idempotency-Key: order-1234-notification-v1" \
>  -d '{
>    "number_id": "<YOUR_NUMBER_ID>",
>    "to": "5511999990000",
>    "type": "text",
>    "text": { "body": "Your order #1234 is ready." }
>  }'

If you call this endpoint again with the same Idempotency-Key within 24 hours, you’ll get the original response without sending a duplicate message.

Sending different message types

Template message

Templates must be pre-approved by Meta. Use them for the first message to a user (outside of a conversation window).

1{
2  "number_id": "<YOUR_NUMBER_ID>",
3  "to": "5511999990000",
4  "type": "template",
5  "template": {
6    "name": "order_confirmation",
7    "language": { "code": "pt_BR" },
8    "components": [
9      {
10        "type": "body",
11        "parameters": [
12          { "type": "text", "text": "1234" }
13        ]
14      }
15    ]
16  }
17}

Image message

1{
2  "number_id": "<YOUR_NUMBER_ID>",
3  "to": "5511999990000",
4  "type": "image",
5  "image": {
6    "link": "https://your-cdn.com/receipt-1234.png",
7    "caption": "Your receipt"
8  }
9}

Document message

1{
2  "number_id": "<YOUR_NUMBER_ID>",
3  "to": "5511999990000",
4  "type": "document",
5  "document": {
6    "link": "https://your-cdn.com/invoice-1234.pdf",
7    "filename": "invoice-1234.pdf",
8    "caption": "Invoice #1234"
9  }
10}

Handling errors

HTTP StatusError codeMeaning
401UNAUTHORIZEDInvalid or revoked API key
403FORBIDDENNumber belongs to a different account
404NOT_FOUNDNumber ID not found
422VALIDATION_ERRORMissing or invalid fields in request body
1{
2  "error": {
3    "code": "NOT_FOUND",
4    "message": "Number not found",
5    "status": 404
6  }
7}

Track delivery status

Check the message status after sending:

$curl "https://dev.muchau.com.br/api/messages/<msg_id>" \
>  -H "Authorization: Bearer $MUCHAW_API_KEY"

Or set up a webhook for message.delivered and message.read events for real-time updates.