Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.relayos.com.br/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through the minimum set of API calls needed to send a WhatsApp message with RelayOS. You will create a project, attach your Meta credentials, send a message, and verify its status — all in under five minutes. You only need curl and a Meta-approved WhatsApp Business account to follow along.
1

Create a project and get your API key

Every RelayOS integration starts with a project. A project holds your Meta credentials, your webhook configuration, and the API keys your services use to authenticate. Create one by sending your project name and owner email to POST /v1/projects.
curl -X POST https://api.relayos.com.br/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "ownerEmail": "you@yourcompany.com"
  }'
The response includes your API key in the apiKey field:
{
  "id": "proj_...",
  "name": "My Project",
  "apiKey": "rly_live_xxxxxxxxxxxxxxxxxxxx"
}
Copy the apiKey value now. RelayOS shows it only once and cannot retrieve it later. Store it in your password manager or secrets vault before continuing.
Set it as an environment variable so the remaining commands can reference it:
export RELAYOS_API_KEY="rly_live_xxxxxxxxxxxxxxxxxxxx"
2

Configure your Meta credentials

Before you can send messages, RelayOS needs to know which WhatsApp Business phone number to use and how to authenticate with Meta on your behalf. You will also set a callbackUrl here if you want real-time status webhooks.You need two values from the Meta for Developers dashboard:
  • Phone Number ID — found in your WhatsApp Business app settings under the phone number you have registered
  • Access Token — a permanent or long-lived system user token with whatsapp_business_messaging permission
curl -X PUT https://api.relayos.com.br/v1/projects/me/meta-credentials \
  -H "Authorization: Bearer $RELAYOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metaPhoneNumberId": "YOUR_PHONE_NUMBER_ID",
    "metaAccessToken": "YOUR_META_ACCESS_TOKEN",
    "callbackUrl": "https://yoursite.com/relayos-webhook"
  }'
The callbackUrl field is optional. If you omit it, RelayOS still sends messages and tracks delivery status — you just will not receive webhook notifications. You can add or update it at any time by calling this endpoint again.
A 200 OK response with the updated project object confirms your credentials were saved.
3

Send a message

With your credentials in place, you can send a WhatsApp message. RelayOS only sends messages using Meta-approved templates, which ensures compliance with WhatsApp’s messaging policies. The hello_world template is pre-approved on every new WhatsApp Business account and works for testing.
curl -X POST https://api.relayos.com.br/v1/messages \
  -H "Authorization: Bearer $RELAYOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999998888",
    "template": "hello_world",
    "language": "en_US"
  }'
Replace +5511999998888 with the phone number you want to reach, in E.164 format (country code prefix, no spaces or dashes).The API responds immediately with a queued message object:
{
  "id": "msg_...",
  "status": "QUEUED",
  "to": "+5511999998888",
  "template": "hello_world",
  "queuedAt": "2026-05-14T10:00:00Z"
}
Save the id field — you will use it in the next step to check delivery status.
For production messages, include an Idempotency-Key header with a unique value per message (for example, your internal order ID). This prevents duplicate sends if your client retries the request due to a network timeout.
4

Check message status

Message delivery through WhatsApp is asynchronous. The status moves through a lifecycle: QUEUED → SENT → DELIVERED → READ, or FAILED if all retry attempts are exhausted. You can poll for the current status at any time using the message ID from the previous step.
curl https://api.relayos.com.br/v1/messages/msg_... \
  -H "Authorization: Bearer $RELAYOS_API_KEY"

{
  "id": "msg_...",
  "status": "DELIVERED",
  "to": "+5511999998888",
  "template": "hello_world",
  "queuedAt": "2026-05-14T10:00:00Z"
}
Rather than polling, configure a callbackUrl in step 2 to receive a webhook POST each time the status changes. See the Webhooks guide for the full event payload reference.
You have created a project, connected your Meta credentials, sent a WhatsApp message, and confirmed delivery — your RelayOS integration is working. From here, explore the send message guide to learn about template variables and idempotency, or browse the API reference for the full parameter list.