> ## 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.

# Quickstart: Send Your First WhatsApp Message

> Learn how to create a RelayOS project, configure Meta credentials, and send your first WhatsApp message in under 5 minutes with three API calls.

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.

<Steps>
  <Step title="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`.

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "id": "proj_...",
      "name": "My Project",
      "apiKey": "rly_live_xxxxxxxxxxxxxxxxxxxx"
    }
    ```

    <Warning>
      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.
    </Warning>

    Set it as an environment variable so the remaining commands can reference it:

    ```bash theme={null}
    export RELAYOS_API_KEY="rly_live_xxxxxxxxxxxxxxxxxxxx"
    ```
  </Step>

  <Step title="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](https://developers.facebook.com):

    * **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

    ```bash theme={null}
    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"
      }'
    ```

    <Note>
      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.
    </Note>

    A `200 OK` response with the updated project object confirms your credentials were saved.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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.

    ```bash theme={null}
    curl https://api.relayos.com.br/v1/messages/msg_... \
      -H "Authorization: Bearer $RELAYOS_API_KEY"
    ```

    ```json theme={null}
    {
      "id": "msg_...",
      "status": "DELIVERED",
      "to": "+5511999998888",
      "template": "hello_world",
      "queuedAt": "2026-05-14T10:00:00Z"
    }
    ```

    <Note>
      Rather than polling, configure a `callbackUrl` in step 2 to receive a webhook POST each time the status changes. See the [Webhooks guide](/guides/webhooks) for the full event payload reference.
    </Note>
  </Step>
</Steps>

<Check>
  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](/guides/send-message) to learn about template variables and idempotency, or browse the [API reference](/api-reference/messages/send) for the full parameter list.
</Check>