> For the complete documentation index, see [llms.txt](https://docs.otima.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otima.io/whatsapp/recursos-de-api/identificadores-de-usuario-e-destinatario.md).

# Identificadores de Usuário e Destinatário

A API do WhatsApp Business permite que o destinatário de uma mensagem seja identificado de diferentes formas, dependendo do contexto da integração e da disponibilidade dos dados do usuário.

Envie mensagens usando o **número de telefone** ou o **BSUID** no campo `to`.

O `@username` identifica o usuário nos dados recebidos da Meta. Ele não é um destinatário de envio.

#### Visão geral

<table><thead><tr><th>Identificador</th><th width="162.9896240234375">Campo de envio</th><th width="223.96875">Exemplo</th><th>Uso</th></tr></thead><tbody><tr><td>Número de telefone</td><td><code>to</code></td><td><code>5511999999999</code></td><td>Formato internacional, normalmente apenas com dígitos.</td></tr><tr><td>BSUID</td><td><code>to</code></td><td><code>BR.13491208655302741918</code></td><td>Identificador do usuário no business portfolio.</td></tr><tr><td><code>@username</code></td><td>Não se aplica</td><td><code>@joao</code></td><td>Dado auxiliar, associado ao BSUID recebido.</td></tr><tr><td></td><td></td><td></td><td></td></tr></tbody></table>

#### BSUID

BSUID significa **Business-Scoped User ID**. A Meta o gera para identificar um usuário dentro de um business portfolio.

<table><thead><tr><th width="197.65625">Característica</th><th>Descrição</th></tr></thead><tbody><tr><td>Formato</td><td>Use o valor completo, incluindo o prefixo do país e o ponto.</td></tr><tr><td>Escopo</td><td>É específico do business portfolio.</td></tr><tr><td>Persistência</td><td>Armazene-o quando o telefone não estiver disponível.</td></tr><tr><td>Alterações</td><td>Pode mudar se o usuário trocar o número de telefone.</td></tr></tbody></table>

```
US.13491208655302741918
```

Não altere, normalize ou remova o prefixo do BSUID.

#### @Username

O usuário pode escolher um username público em seu próprio WhatsApp, como `@joao`. A Meta pode enviá-lo em webhooks e dados de contato.

Armazene o username junto ao BSUID. recebido Use sempre o BSUID associado no campo `to`.

{% stepper %}
{% step %}

#### Receba os dados do contato

O usuário inicia uma conversa com a empresa. A Meta envia o username e o BSUID, quando disponíveis.
{% endstep %}

{% step %}

#### Associe os identificadores

Persista a relação entre `profile.username` e `user_id`.
{% endstep %}

{% step %}

#### Envie usando o BSUID

Use o valor de `user_id` no campo `to` das próximas mensagens.
{% endstep %}
{% endstepper %}

#### Campo oficial do destinatário

O campo `to` define o destinatário e o tipo de identificador usado pela Meta.

| Identificador      | Campo | Exemplo                   |
| ------------------ | ----- | ------------------------- |
| Número de telefone | `to`  | `5511999999999`           |
| BSUID              | `to`  | `US.13491208655302741918` |

### Envio para número de telefone

{% code overflow="wrap" expandable="true" %}

```bash
curl -X POST "https://sync-core-api.otima.io/whatsapp/provider/{NUMERO_AQUI}/send-message" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {SEU_TOKEN}" \
  -H "x-workspace-uuid: {SEU_UUID_WORKSPACE}" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "text",
    "text": {
      "body": "Olá! Mensagem via telefone."
    }
  }'
```

{% endcode %}

#### Envio para BSUID

Envie o BSUID completo no campo `to`.

{% code overflow="wrap" expandable="true" %}

```bash
curl -X POST "https://sync-core-api.otima.io/whatsapp/provider/{NUMERO_AQUI}/send-message" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {SEU_TOKEN}" \
  -H "x-workspace-uuid: {SEU_UUID_WORKSPACE}" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "US.13491208655302741918",
    "type": "text",
    "text": {
      "body": "Olá! Mensagem via BSUID."
    }
  }'
```

{% endcode %}

#### Webhook com username e BSUID

O trecho abaixo representa `value` no webhook oficial da Meta.

{% code overflow="wrap" expandable="true" %}

```json
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "profile": {
        "username": "@joao",
        "country_code": "BR"
      },
      "wa_id": "",
      "user_id": "BR.13491208655302741918"
    }
  ],
  "messages": [
    {
      "from": "",
      "from_user_id": "BR.13491208655302741918",
      "id": "wamid.HBgL...",
      "timestamp": "<UNIX_TIMESTAMP>",
      "type": "text",
      "text": {
        "body": "Olá"
      }
    }
  ]
}
```

{% endcode %}

| Campo                          | Descrição                            |
| ------------------------------ | ------------------------------------ |
| `contacts[0].profile.username` | Username público, quando disponível. |
| `contacts[0].user_id`          | BSUID do usuário.                    |
| `contacts[0].wa_id`            | Número do usuário. Pode estar vazio. |
| `messages[0].from_user_id`     | BSUID do remetente.                  |

#### Resposta imediata

A aceitação do envio retorna o ID da mensagem em `messages[].id`.

```json
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "US.13491208655302741918",
      "wa_id": "",
      "user_id": "US.13491208655302741918"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgL..."
    }
  ]
}
```

`wa_id` pode ser uma string vazia quando o telefone não estiver disponível.

{% hint style="success" %}

#### Restrições e boas práticas

* O BSUID precisa pertencer ao business portfolio do número remetente.
* Templates one-tap, zero-tap e copy-code exigem um número de telefone.
* Persista `user_id`, `profile.username` e o `wamid` retornado pela Meta.
  {% endhint %}