> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aplicativo de exemplo: códigos de verificação e convites por SMS

> Como o aplicativo de exemplo Clean Beans verifica números de telefone com códigos de uso único e convida pessoas por SMS ou email usando o OneSignal.

Esta página faz parte de [Aplicativo de exemplo: uma integração completa do OneSignal](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-overview.md), que acompanha um aplicativo real do início ao fim. O aplicativo é o **Clean Beans**, uma escala de limpeza para casas compartilhadas, construído com Expo (React Native) e um backend Supabase.

O Clean Beans usa SMS para duas tarefas que push e email não fazem bem: comprovar que um número de telefone pertence a quem o digitou e alcançar alguém que ainda não tem o aplicativo.

| Mensagem | Enviada para | Gatilho |
| - | - | - |
| Código de verificação | O número que um usuário conectado acabou de inserir | Chamada a partir do aplicativo |
| Convite para a casa | Um número de telefone ou endereço de email de alguém sem conta | Chamada a partir do aplicativo |

Ambas são enviadas para um **contato bruto**, um número de telefone ou endereço de email, e não para um External ID. Essa é a principal diferença em relação a todos os outros envios deste guia.

## Verificar um número de telefone com um código de uso único \\

Em User Profile, um usuário pode adicionar um número de celular. O aplicativo pede ao backend que envie um código de 6 dígitos por SMS, o usuário o digita e o backend o verifica. Só então o número é considerado verificado.

![O card do número de telefone em três estados: inserindo o número, inserindo o código e verificado](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-phone-verification.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=ae377258019c7454d600dc86bb722cce)

Adicionando um número de telefone: inserir o número, inserir o código, verificado.

O OneSignal entrega a mensagem de texto. Ele não cria nem verifica o código. Todo o resto é trabalho do seu backend.

**1. Gerar um código e armazená-lo com hash**

O código vem de uma fonte aleatória criptográfica. Apenas um hash com chave é armazenado, vinculado ao usuário e ao número de telefone, de modo que a tabela sozinha não permite recuperar os códigos. A chave é um segredo dedicado, `OTP_HASH_SECRET`, que não é usado para mais nada. As duas funções se recusam a rodar se ele não estiver definido.

```typescript supabase/functions/_shared/otp.ts theme={null}
export function generateCode(): string {
  const limit = 4_000_000_000; // a multiple of 1,000,000 below 2^32, so no code is more likely than another
  const buf = new Uint32Array(1);
  do {
    crypto.getRandomValues(buf);
  } while (buf[0] >= limit);
  return String(buf[0] % 1_000_000).padStart(6, '0');
}

export async function hashCode(secret: string, userId: string, phone: string, code: string): Promise<string> {
  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign'],
  );
  const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${userId}:${phone}:${code}`));
  return Array.from(new Uint8Array(sig), (b) => b.toString(16).padStart(2, '0')).join('');
}
```

```typescript supabase/functions/send-otp/index.ts theme={null}
const { data: inserted, error: insertErr } = await supabase
  .from('phone_otp_codes')
  .insert({
    user_id: user.id,
    phone,
    code_hash: codeHash,
    expires_at: new Date(now.getTime() + OTP_TTL_MINUTES * 60_000).toISOString(),
  })
  .select('id')
  .single();
```

**2. Enviá-lo por SMS pelo OneSignal**

`include_phone_numbers` direciona diretamente para o número. Se o OneSignal nunca o viu, ele cria uma Subscription de SMS para esse número.

```typescript supabase/functions/send-otp/index.ts theme={null}
const onesignalPayload = {
  app_id: ONESIGNAL_APP_ID,
  target_channel: 'sms',
  // Targets a raw phone number. OneSignal creates an SMS subscription
  // for it if one does not exist yet.
  include_phone_numbers: [phone],
  ...(ONESIGNAL_SMS_FROM ? { sms_from: ONESIGNAL_SMS_FROM } : {}),
  name: 'Phone verification code',
  contents: {
    en: `Your Clean Beans verification code is ${code}. It expires in ${OTP_TTL_MINUTES} minutes.`,
  },
};
```

**3. Verificar o código**

O backend calcula o hash do que o usuário digitou e o compara com o hash armazenado. Cada tentativa errada é contada. Depois de cinco, o código deixa de valer e é preciso solicitar um novo.

```typescript supabase/functions/verify-otp/index.ts theme={null}
const submittedHash = await hashCode(OTP_HASH_SECRET, user.id, phone, code);

if (!safeEqual(submittedHash, row.code_hash)) {
  const attempts = row.attempts + 1;
  await supabase.from('phone_otp_codes').update({ attempts }).eq('id', row.id);

  const left = OTP_MAX_ATTEMPTS - attempts;
  return jsonResponse({
    error: 'invalid_code',
    message: left > 0
      ? `That code is not right. ${left} ${left === 1 ? 'attempt' : 'attempts'} left.`
      : 'Too many wrong attempts. Request a new code.',
    attemptsLeft: Math.max(left, 0),
  }, 400);
}
```

**4. Registrar o número como Subscription de SMS**

Depois que o backend confirma o código, o aplicativo adiciona o número ao usuário conectado.

```typescript src/lib/phone.ts theme={null}
export async function confirmPhoneCode(phone: string, code: string): Promise<void> {
  await callFunction('verify-otp', { body: { phone, code } });
  OneSignal.User.addSms(phone);
}
```

O aplicativo repete isso a cada login, para que um número verificado acompanhe o usuário em um novo dispositivo.

```typescript src/lib/phone.ts theme={null}
export async function syncOneSignalSms(): Promise<void> {
  try {
    const phone = await loadVerifiedPhone();
    if (phone) {
      OneSignal.User.addSms(phone);
      console.log('[phone] SMS subscription synced');
    }
  } catch (e) {
    console.warn('[phone] syncOneSignalSms error:', e);
  }
}
```

> [!NOTE]
>
> Chame `addSms()` depois de `login()`, como no email. Um envio para um número de telefone bruto cria uma Subscription que não pertence a ninguém. `addSms()` a partir de um aplicativo com usuário conectado vincula essa Subscription ao usuário. Até lá, ela aparece no painel como um registro de usuário separado.

## Proteger o endpoint \\

Uma função que envia uma mensagem de texto sob demanda custa dinheiro a cada execução e é alvo de abuso. O Clean Beans aplica estes limites.

| Regra | Valor |
| - | - |
| Validade do código | 10 minutos |
| Tentativas erradas permitidas | 5 |
| Espera antes de reenviar | 30 segundos |
| Códigos por usuário | 3 a cada 10 minutos |
| Usos por código | Um. Um novo código substitui qualquer anterior |

```typescript supabase/functions/send-otp/index.ts theme={null}
const MAX_CODES_PER_WINDOW = 3;
const WINDOW_MINUTES = 10;
const RESEND_COOLDOWN_SECONDS = 30;
```

O número verificado fica em uma tabela própria. Somente o backend pode gravar nela, então o aplicativo não pode marcar um número como verificado, e os outros membros de uma casa não podem lê-lo.

```sql supabase/migrations/028_phone_verification_and_invites.sql theme={null}
create table if not exists public.user_phones (
  user_id     uuid primary key references public.profiles(id) on delete cascade,
  phone       text not null,                       -- E.164, e.g. +14155551234
  verified_at timestamptz not null default now()
);
```

## Pedir consentimento onde o número é inserido \\

Um número de telefone, por si só, não é permissão para enviar mensagens. Para códigos de verificação, basta um aviso ao lado do campo de telefone, que deve dizer quem está enviando, o que será enviado, que tarifas podem ser cobradas e como cancelar.

```tsx src/components/PhoneVerificationCard.tsx theme={null}
{/* Consent disclosure: must sit next to the phone field */}
<Text style={styles.disclosure}>
  Enter your mobile number to receive verification codes by text message from Clean Beans.
  Msg & data rates may apply. Reply STOP to opt out.
</Text>
```

## Convidar alguém que ainda não é usuário \\

Na tela Household, um membro pode convidar alguém por SMS ou por email. A pessoa convidada não tem conta, nem dispositivo registrado, nem External ID. O backend envia para o contato bruto, com um link que abre a tela de entrada do aplicativo.

![O diálogo de convite e a mensagem de texto de convite que ele envia](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-invitation.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=78d087c22898bc9876dbdd1f90c56033)

Convidando um colega de casa por SMS ou email, e a mensagem que ele recebe.

O mesmo endpoint trata os dois canais. O SMS usa `include_phone_numbers`. O email usa `email_to`, com o assunto e o corpo HTML passados diretamente na solicitação.

```typescript supabase/functions/send-invite/index.ts theme={null}
const joinUrl = `${JOIN_URL}?code=${encodeURIComponent(household.invite_code)}`;

const onesignalPayload: Record<string, unknown> = channel === 'sms'
  ? {
      app_id: ONESIGNAL_APP_ID,
      target_channel: 'sms',
      // Raw phone number: OneSignal creates an SMS subscription if needed
      include_phone_numbers: [contact],
      ...(ONESIGNAL_SMS_FROM ? { sms_from: ONESIGNAL_SMS_FROM } : {}),
      name: 'Household invitation (SMS)',
      contents: {
        en: `${inviterName} invited you to join "${householdName}" on Clean Beans, the cleaning rota app. Join: ${joinUrl} Reply STOP to opt out.`,
      },
    }
  : {
      app_id: ONESIGNAL_APP_ID,
      target_channel: 'email',
      // Raw email address: OneSignal creates an email subscription if needed
      email_to: [contact],
      name: 'Household invitation (email)',
      email_subject: `${inviterName} invited you to Clean Beans`,
      email_preheader: `Join "${householdName}" and share the cleaning.`,
      email_body: buildInviteEmail(inviterName, householdName, joinUrl, household.invite_code),
      // Keep the join link exactly as written. Click tracking would wrap
      // it in a redirect, and it would stop opening the app directly.
      disable_email_click_tracking: true,
    };
```

O link é um Universal Link, configurado em [Abrir o aplicativo a partir de links web comuns](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links). Dois detalhes o mantêm funcionando:

* **O rastreamento de cliques do email está desativado.** O rastreamento reescreve os links para passarem por um domínio de rastreamento, e um link reescrito não abre mais o aplicativo.
* **O SMS não usa um link curto rastreado**, pelo mesmo motivo.

Quando a pessoa convidada instala o aplicativo e faz login, as chamadas `login()` e `addEmail()` ou `addSms()` do aplicativo vinculam ao novo usuário a Subscription que o convite criou.

> [!WARNING]
>
> A pessoa convidada não concordou em receber mensagens do seu aplicativo. As regras para SMS e emails não solicitados variam de país para país e podem ser rígidas. O Clean Beans inclui esse fluxo para mostrar como funciona o envio para um contato bruto, e limita cada membro a dez convites por dia. Antes de usar esse padrão em produção, verifique as regras dos lugares para onde você envia e considere fazer com que quem convida envie a mensagem do próprio telefone.

## O que é bom saber \\

* **É necessário um remetente.** Escolha um remetente padrão em **Settings > SMS** ou passe `sms_from` em cada solicitação. Sem nenhum dos dois, a solicitação é rejeitada com "A valid number is required for 'From' field".
* **Uma resposta `200` nem sempre significa que uma mensagem foi enviada.** Verifique se há um `id` de mensagem na resposta, e não apenas o código de status.
* **Armazene os números no formato E.164**, um sinal de mais seguido do código do país e do número, e rejeite qualquer outro formato antes de chamar a API.
* **O OneSignal Verify é a alternativa gerenciada.** Ele gera e verifica os códigos para você. O Clean Beans cria os próprios para mostrar o fluxo completo.

**Configuração do painel.** Conclua a [configuração de SMS](https://documentation.onesignal.com/docs/pt-BR/sms-setup.md) e escolha um remetente padrão que alcance os países onde estão seus usuários.

> [card] [Senhas de uso único](https://documentation.onesignal.com/docs/pt-BR/sms-verify.md)
>
> OneSignal Verify e como criar sua própria solução.

> [card] [Opt-in e coleta de SMS](https://documentation.onesignal.com/docs/pt-BR/sms-opt-in-and-collection.md)
>
> Requisitos de consentimento e avisos.

> [card] [Referência da API de SMS](https://documentation.onesignal.com/reference/sms.md)
>
> Todos os parâmetros de SMS.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.