# Migrar de outro provedor

> O que muda ao trazer sua integração de outro provedor para o Messajo.

## Quanto muda

O esforço depende de onde você vem. Quem já usa a API oficial troca pouco; quem vem de uma API não oficial troca o modelo.

| Você vem de | Envio | Webhooks | Esforço |
|---|---|---|---|
| Cloud API direto | Mesmo corpo na camada espelho; troca a URL base e o token | Formato `meta`: o mesmo `value` que você já trata | Pequeno |
| 360dialog | Mesmo corpo na camada espelho; troca a URL, o `D360-API-KEY` e põe o `phone_number_id` no caminho | Formato `meta` | Pequeno |
| Twilio | Reescrever: camada simples ou espelho | Status viram `message.status` | Médio |
| Evolution, WAHA, Z-API, uazapi | Reescrever e adotar as regras da Meta (janela, templates, opt-in) | Formato `normalized` ou `meta` | Grande |

As duas camadas da API (espelho da Meta e simples) usam a mesma chave. Veja [Conceitos](/start/concepts/).

## Vindo da Cloud API ou da 360dialog

A camada espelho recebe o **mesmo corpo da Meta**, campo por campo. O código que monta a mensagem fica igual; mudam a URL e a autenticação.

| | Antes | No Messajo |
|---|---|---|
| Cloud API | `POST https://graph.facebook.com/<versão>/{phone_number_id}/messages` | `POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages` |
| 360dialog | `POST https://waba-v2.360dialog.io/messages` | `POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages` |
| Autenticação | `Authorization: Bearer <token da Meta>` ou `D360-API-KEY: <chave>` | `Authorization: Bearer mj_...` |

```bash
curl -X POST "https://api.messajo.com/v1/whatsapp/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Olá do Messajo" }
  }'
```

- Na 360dialog a chave já diz qual é o número. No Messajo a chave vale para a organização, então o `phone_number_id` vai no caminho. Ele aparece na página da conexão.
- O cabeçalho `D360-API-KEY` sai; entra `Authorization: Bearer` com uma [chave de API](/api/authentication/) com permissão `send`.
- O token da Meta não fica mais no seu código: o Messajo guarda o token da conexão, cifrado.
- A resposta e os erros da Meta voltam como vieram, com o mesmo corpo `{ "error": { "code", … } }` que o seu código já trata. Só os erros do próprio Messajo (chave, permissão, limite) usam o [formato único](/errors/).
- Nos webhooks, escolha o formato `meta` no destino para receber o mesmo `value` que a Meta manda, dentro do envelope do Messajo. Veja [Eventos](/webhooks/events/).

### O que o espelho aceita

O caminho é `/v1/whatsapp/{id}/<resto do caminho da Meta>`, com o método, a query e o corpo da Meta. A versão da Graph API é a do servidor.

| `{id}` | Vai para | Exemplo |
|---|---|---|
| `phone_number_id` de uma conexão sua | o número | `POST /v1/whatsapp/{phone_number_id}/messages`, `GET …/whatsapp_business_profile`, `POST …/media` |
| `waba_id` (conta de mensagens) de uma conexão sua | a conta | `GET /v1/whatsapp/{waba_id}/message_templates` |
| `phone_number_id` + `nodes/{node_id}` | um nó avulso da Meta | `GET /v1/whatsapp/{phone_number_id}/nodes/{media_id}`, `DELETE …/nodes/{template_id}` |

O `waba_id` aparece na página da conexão, em **Conta de mensagens (WABA)**. Nós avulsos (mídia, template por id) passam pelo número, para o Messajo saber de qual conexão é o pedido.

- **Permissão da chave:** `POST …/messages` pede `send`; `message_templates` e nós de template pedem `templates`; outros `GET`, `read`; outras alterações, `admin`. Chave presa a algumas conexões só alcança essas.
- **Bloqueados** com `403` [`mirror_path_blocked`](/errors#mirror_path_blocked), porque derrubam a conexão: `register`, `deregister`, `request_code`, `verify_code`, `smb_app_data`, `DELETE …/subscribed_apps` e `POST …/subscribed_apps` com `override_callback_uri`.
- **Envio:** `POST …/messages` passa pelo mesmo limite por número da camada simples ([Envio por número](/api/limits#envio-por-número)), grava a mensagem nos logs, emite `message.sent` e devolve o id do Messajo no cabeçalho `X-Messajo-Message-Id`. O Messajo não repete o envio quando a Meta falha.
- **Resposta:** status, corpo e `content-type` da Meta, mais `X-Request-Id`. O `Authorization` que você manda nunca segue para a Meta.

## Vindo do Twilio

O Twilio tem formato próprio (`From`, `To` e `Body` com o prefixo `whatsapp:`, em formulário), então a chamada de envio é reescrita:

- **camada simples** (`POST /v1/messages`), para texto, mídia, template e botões com o mesmo formato nos 3 canais;
- **camada espelho**, para usar qualquer recurso da Meta com o corpo dela.

Os status do Twilio (`queued`, `sent`, `delivered`, `read`, `failed`) chegam como o evento `message.status`, e as mensagens recebidas como `message.received`. Troque o `StatusCallback` e o webhook de entrada por um [destino de eventos](/webhooks/events/) e passe a [verificar a assinatura](/webhooks/verify-signature/) do Messajo no lugar da `X-Twilio-Signature`. Os templates aprovados ficam na sua conta da Meta: sincronize ou recrie no Messajo.

## Vindo de API não oficial

Evolution, WAHA, Z-API e uazapi simulam um celular. O Messajo usa a API oficial da Meta, e isso muda o modelo:

| Na API não oficial | No Messajo |
|---|---|
| Ler o QR code | Cadastro oficial da Meta (Embedded Signup), pelo painel |
| Instância | Conexão |
| Mandar qualquer mensagem a qualquer hora | Fora da janela de 24 h, só **template aprovado** |
| Lista comprada ou contato que nunca falou com você | **Opt-in**: a pessoa precisa ter aceitado receber mensagens |
| Sem custo por mensagem | A Meta cobra por mensagem de template, direto de você |
| Risco de bloqueio do número | Número oficial, com qualidade e limite medidos pela Meta |

Para não perder o atendimento no celular, conecte em **coexistência**: o app do WhatsApp Business continua funcionando e o Messajo traz os contatos e até 6 meses de histórico, uma única vez, na hora de conectar. Grupos não sincronizam na coexistência. Veja [Conectar o WhatsApp](/connect/whatsapp/).

Desligue a API antiga só depois que a conexão oficial estiver ativa e testada, e desconecte dela o aparelho pareado pelo QR code.

## O número já está em outro parceiro

Depende do modo:

- **Só API**: no novo modelo de conta da Meta, o número pode ter vários parceiros ao mesmo tempo. Conecte pelo Messajo sem tirar do parceiro atual, migre aos poucos e desligue o antigo quando terminar. Veja o [guia da Meta sobre o novo modelo de conta](https://developers.facebook.com/documentation/business-messaging/whatsapp/account-model-evolution/onboarding/).
- **Coexistência**: um parceiro por vez. Desconecte no app do celular e conecte de novo pelo Messajo, como em [Trocar de parceiro na coexistência](/connect/whatsapp/#trocar-de-parceiro-na-coexistência).

## Checklist de virada

- [ ] Templates sincronizados ou recriados no Messajo, e aprovados.
- [ ] Destinos de eventos criados, com a assinatura verificada no seu servidor.
- [ ] Uma chave de API por integração, com só as permissões e conexões necessárias.
- [ ] Um teste de ponta a ponta com um número seu: enviar, receber, status e template.
- [ ] Integração antiga desligada só depois do teste, e o número desconectado do provedor antigo, se for o caso.
