OnBoarding para Organizações

Neste documento você irá aprender todos os passos necessários para se enviar uma mensagem de WhatsApp através da biblioteca Messagefy.
Você sairá deste OnBoarding sabendo perfeitamente como:

Cadastrar novas contas para sua Organização usando a sua APIKEY

Buscar a APIKEY da conta

Cadastrar o canal de WebHook, necessários para enviar dados para o seu sistema

Cadastrar o canal de Whatsapp, que será usado para conectar o celular

Conectar usando QRCode ou PairCode

Receber o QRCode e PairCode para conexão

Enviar sua primeira Mensagem

1) Solicite um EndPoint de Sandbox e sua APIKEY de Organização

Antes de começar, você precisa ter em mãos uma chave de api de organização e o EndPoint do Messagefy.

Exemplo:
EndPoint Principal da API: http://localhost:7777
Organization APIKEY: org_019c0020-2309-7dea-a7d6-1163bb1ddc7a

2) Verifique seu acesso com o EndPoint "me"

Faça o primeiro teste de acesso, usando o método /api/v1/me, que retorna os dados a respeito da sua chave de API:

Request

Result esperado

3) Liste suas contas usando sua ApiKey de Organização

use o endpoint /admin/account com GET.
Normalmente, não existirão contas cadastradas.

Request

Result esperado

4) Criação de uma nova Conta

Use o método POST /api/v1/admin/account para criar uma nova conta para sua organização.
Com a criação da nova conta, uma APIKEY exclusiva para uso da conta será automaticamente criada.

Request

Result esperado

Anote o accountId para usar na próxima etapa

5) Busque a APIKEY da Conta que foi criada

Ou, busque a APIKEY de uma conta já existente com /api/v1/admin/apikey?accountId.
A criação da uma nova conta leva à criação de uma APIKEY exclusiva para a conta recem criada, com prefixo acc_, que será usada para todos os procedimentos que envolvem a conta. Nesta etapa vamos descobrir a API_KEY exclusiva da conta.

Para listar as APIKEYs de contas você ainda deve-se usar a APIKEY da organização.

Request

Result esperado

Anote a APIKEY da Conta para as próximas etapas.

6) Criação do Canal de WebHook

O canal de WebHook serve para enviar todos as mensagens e respostas de comandos para o seu sistema. Ele é essencial para:

Receber mensagens que foram enviadas para o WhatsApp registrado.

Receber respostas de comandos (geração de QRCode, PairCode, Envio de Mensagens, etc).

Acompanhar a situação da sessão do Whatsapp no Messagefy.

📌

Perceba que a partir daqui você deve usar a APIKEY da conta e não da organização.

Request

curl --location --request POST 'http://localhost:7777/api/v1/admin/channel' \
--header 'api-key: acc_019bfb71-0000-0000-0000-41cd513cacca' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Canal webhook",
    "description": "webhook feedback",
    "channelType": "http-sender",
    "accountId": "019bfb71-0d7b-715a-af8c-84b3e58e73c3",
    "parameters": {
        "url": "https://webhook.site/d124df93-a65a-44c4-9d5b-22ceb986dac6"
    }
}'

Recomendações:

em name e description sempre informe algo que informe claramente que se trata do canal de WebHook.

accountId é o código da conta que foi criado no procedimento 5

channelType é sempre http-sender para o canal de WebHook

Informe em parameters.url o endereço http onde vc deseja receber os WebHooks

É indispensável que vc tenha acesso aos dados que serão enviados para o endereço de WebHook (parameters.url).
Caso esteja apenas testando a rotina, informe um endereço onde você possa receber temporariamente os payloads. Ex: Gere e use uma url do webhook.site .

Response esperado

{
    "channelId": "019c04a3-3eee-7dcc-9964-530445ee28c6",
    "feedbackChannelId": null,
    "name": "Canal webhook",
    "description": "webhook feedback",
    "account": {
        "accountId": "019c0496-9ad6-70cb-b5fa-326e4f970fa5",
        "name": "MessageFy",
        "description": "Conta principal do MessageFy",
        "status": {
            "accountStatusId": 2,
            "name": "Ativo",
            "icon": null,
            "description": "Pronto para uso",
            "canManageChildObjects": true,
            "canSendAndReceiveMessage": true
        },
        "organization": {
            "organizationId": "019c0496-96de-7df6-91b0-124c3ff0b930",
            "name": "ChatGuru",
            "description": "Organização do ChatGuru",
            "status": {
                "organizationStatusId": 2,
                "name": "Ativo",
                "icon": null,
                "description": "Pronto para uso",
                "canManageChildObjects": true,
                "canSendAndReceiveMessage": true
            }
        }
    },
    "channelType": {
        "channelTypeId": 4,
        "key": "http-sender",
        "name": "HTTP API & WebHook Sender",
        "description": "",
        "requiredFeedbackChannel": false,
        "canBeFeedbackChannel": true,
        "requireReceiverChannel": false,
        "canBeReceiverChannel": false
    },
    "status": {
        "channelStatusId": 4,
        "name": "Running",
        "icon": null,
        "description": "Pronto para uso",
        "canSendAndReceiveMessage": true,
        "canConfigure": false
    },
    "provider": {
        "providerId": "019c0496-8e9a-71b0-ad0c-2afbbaa86f44",
        "key": "http-sender",
        "name": "http-sender",
        "description": null,
        "icon": null,
        "channelTypeId": 0,
        "channelTypeKey": null,
        "channelTypeName": null,
        "priority": 1,
        "dockerImage": null,
        "platform": null,
        "maxChannelsPerInstance": null,
        "requiresCluster": false,
        "requiresMessageBroker": false,
        "requiresDatabase": false
    },
    "parameters": {
        "url": "https://webhook.site/#!/view/d124df93-a65a-44c4-9d5b-22ceb986dac6"
    },
    "devices": null
}

Anote o channelId que foi gerado para o canal de WebHook

7) Criação do Canal de WhatsApp

Este canal é utilizado para conexão do Celular ao Whatsapp, sendo que mensagens recebidas, respostas de comandos, QRCodes e PairCodes de conexão e outros eventos serão enviados para canal de WebHook que foi criado na etapa 6.
Portanto, é necessário informar neste canal o channelId que foi gerado na etapa anterior.

Request

curl --location --request POST 'http://localhost:7777/api/v1/admin/channel' \
--header 'api-key: acc_019c0496-aa45-7de6-800a-9f3788edcb60' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Whatsapp Web",
    "description": "Whatsapp usando o Whatsmeow",
    "channelType": "whatsapp-web",
    "accountId": "019c0496-9ad6-70cb-b5fa-326e4f970fa5",
    "feedbackChannelId": "019bfb74-0554-7682-8bde-31f677e3df23",
    "parameters": {}
}'

Recomendações:

em name e description sempre informe algo que informe claramente que se trata do canal do Whatsapp.

accountId é o código da conta que foi criado no procedimento 5

channelType é sempre whatsapp-web

Informe em feedbackChannelId o channelId do canal de WebHook

Response esperado

{
    "channelId": "019c04a9-b6ab-79af-bf09-713fc1ed282a",
    "feedbackChannelId": "019c04a3-3eee-7dcc-9964-530445ee28c6",
    "name": "Whatsapp Web",
    "description": "Whatsapp não oficial Whatsmeow",
    "account": {
        "accountId": "019c0496-9ad6-70cb-b5fa-326e4f970fa5",
        "name": "MessageFy",
        "description": "Conta principal do MessageFy",
        "status": {
            "accountStatusId": 2,
            "name": "Ativo",
            "icon": null,
            "description": "Pronto para uso",
            "canManageChildObjects": true,
            "canSendAndReceiveMessage": true
        },
        "organization": {
            "organizationId": "019c0496-96de-7df6-91b0-124c3ff0b930",
            "name": "ChatGuru",
            "description": "Organização do ChatGuru",
            "status": {
                "organizationStatusId": 2,
                "name": "Ativo",
                "icon": null,
                "description": "Pronto para uso",
                "canManageChildObjects": true,
                "canSendAndReceiveMessage": true
            }
        }
    },
    "channelType": {
        "channelTypeId": 2,
        "key": "whatsapp-web",
        "name": "WhatsApp Não Oficial",
        "description": "Instâncias que se comportam como uma instância do Whatsapp Web",
        "requiredFeedbackChannel": true,
        "canBeFeedbackChannel": false,
        "requireReceiverChannel": false,
        "canBeReceiverChannel": false
    },
    "status": {
        "channelStatusId": 4,
        "name": "Running",
        "icon": null,
        "description": "Pronto para uso",
        "canSendAndReceiveMessage": true,
        "canConfigure": false
    },
    "provider": {
        "providerId": "019c0496-8d97-784a-9efb-a999ec9ca95f",
        "key": "whatsmeow",
        "name": "whatsmeow",
        "description": null,
        "icon": null,
        "channelTypeId": 0,
        "channelTypeKey": null,
        "channelTypeName": null,
        "priority": 1,
        "dockerImage": null,
        "platform": null,
        "maxChannelsPerInstance": null,
        "requiresCluster": false,
        "requiresMessageBroker": false,
        "requiresDatabase": false
    },
    "parameters": {},
    "devices": null
}

O channelId deste canal é o utilizado para enviar mensagens, solicitar QRCode de conexão, etc. Todos os procedimentos com o Whatsapp dependem deste channelId.

8) Status do Whatsapp

Agora que vc já tem um canal de Whatsapp configurado, você pode solicitar a conexão, enviar comandos e mensagens. Mas antes, vamos verificar a situação da sua instância que é responsável por gerenciar esta conexão.

Perceba que a partir daqui vc sempre vai usar o APIKEY da Conta e o channelId do canal de Whatsapp!

Request

Response esperado

💡

Os resultados de requisições realizados para o canal de Whatsapp são sempre um packageID. O resultado real do comando será enviado para o endereço de WebHook que foi informado no canal WebHook.

Payload enviado para o seu WebHook:

Em caso da instância NÃO estar conectada

Em caso de já ter sido solicitada uma conexão

Caso o usuário já tenha se conectado

9) Solicitar conexão do Whatsapp

Agora vamos conectar a instância do Messagefy ao Whatsapp. Para isso podemos user um comando solicitando a conexão via QRCode ou via PairCode.

Request para se conectar com QRCode:

curl --location --request POST 'http://localhost:7777/api/v1/message/sendcommand' \
--header 'api-key: acc_019c0496-aa45-7de6-800a-9f3788edcb60' \
--header 'Content-Type: application/json' \
--data '{
    "channelId": "019c04a9-b6ab-79af-bf09-713fc1ed282a",
    "content": {
        "commandType": "SESSION_START",
        "type": "SESSION_START_QR_CODE"
    }
}'

A solicitação de conexão usando QRCode dispensa qualquer parâmetro adicional. Basta informar corretamente o channelId.

Request para se conectar usando PairCode

Request

curl --location --request POST 'http://localhost:7777/api/v1/message/sendmessage' \
--header 'api-key: acc_019c0496-aa45-7de6-800a-9f3788edcb60' \
--header 'Content-Type: application/json' \
--data '{
    "channelId": "019c04a9-b6ab-79af-bf09-713fc1ed282a",
    "content": {
        "commandType": "SESSION_START",
        "type": "SESSION_START_PAIR_CODE",
        "mobileNumber": "5511987654321"
    }
}'

A solicitação de conexão usando PairCode exige que seja informado o número do celular do Whatsapp que você deseja conectar (atributo mobileNumber com DDI, DDD e número do telefone, apenas números e sem espaços ou outros caracteres), além de informar corretamente o channelId.

Response esperado

{
    "packageId": "41620d24-3d1a-4d9a-8dcb-50be17d33f86"
}

💡

Response enviado para o seu WebHook:

Conexão via PairCode

Conexão via QRCode

📌

No caso do QRCode, o Whatsapp continuará enviando novos QRCode por aproximadamente 4 minutos caso o anterior não tenha sido lido.
Você receberá um WebHook de cada um destes novos QRCodes e um novo deve ser exibido para seu usuário para que ele realize a conexão.

Caso o usuário não se conecte

O usuário tem aproximadamente 4 minutos para informar o PairCode ou ler o QRCode. Caso isso não seja feito um evento INSTANCE_USER_CONNECT_TIMEOUT será enviado para o seu WebHook.

WebHook

{
   "packageId":"019c04ff-37a1-735e-874c-d681bb09f9c5",
   "channelId":"019c04a9-b6ab-79af-bf09-713fc1ed282a",
   "organizationID":"019c0496-96de-7df6-91b0-124c3ff0b930",
   "organizationName":null,
   "accountId":"019c0496-9ad6-70cb-b5fa-326e4f970fa5",
   "accountName":null,
   "correlationId":null,
   "content":{
      "type":"INSTANCE_USER_CONNECT_TIMEOUT",
      "timestamp":"2026-01-28T14:26:00.7139198+00:00"
   },
   "timestamp":"2026-01-28T14:26:00.7370856+00:00",
   "providerMetadata":null
}

Caso o usuário não se conecte e vc receba o INSTANCE_USER_CONNECT_TIMEOUT, você devera solicitar um novo PairCode ou QRCode novamente e repetir o processo.

10) Recebendo mensagens

Com o canal conectado ao Whatsapp, você comecará a receber WebHooks no canal que foi configurado na etapa 6.

Veja mais detalhes em Recebendo WebHooks

11) Enviar mensagens

Todos os detalhes de com enviar mensagens podem ser vistos neste capítulo:

Texto, imagem, audio, video e documentos

1) Solicite um EndPoint de Sandbox e sua APIKEY de Organização#

2) Verifique seu acesso com o EndPoint "me"#

3) Liste suas contas usando sua ApiKey de Organização#

4) Criação de uma nova Conta#

5) Busque a APIKEY da Conta que foi criada#

6) Criação do Canal de WebHook#

7) Criação do Canal de WhatsApp#

8) Status do Whatsapp#

Payload enviado para o seu WebHook:#

9) Solicitar conexão do Whatsapp#

Request para se conectar com QRCode:#

Request para se conectar usando PairCode#

Response enviado para o seu WebHook:#

Caso o usuário não se conecte#

10) Recebendo mensagens#

11) Enviar mensagens#

1) Solicite um EndPoint de Sandbox e sua APIKEY de Organização

2) Verifique seu acesso com o EndPoint "me"

3) Liste suas contas usando sua ApiKey de Organização

4) Criação de uma nova Conta

5) Busque a APIKEY da Conta que foi criada

6) Criação do Canal de WebHook

7) Criação do Canal de WhatsApp

8) Status do Whatsapp

Payload enviado para o seu WebHook:

9) Solicitar conexão do Whatsapp

Request para se conectar com QRCode:

Request para se conectar usando PairCode

Response enviado para o seu WebHook:

Caso o usuário não se conecte

10) Recebendo mensagens

11) Enviar mensagens