Um utilizador escreve no Viber e ninguém responde. Um cenário familiar para pequenos negócios: um gestor, três mensageiros e os clientes vão para quem respondeu primeiro. Um chatbot resolve este problema de forma radical: funciona 24 horas por dia, não se cansa e reage instantaneamente.

Anteriormente, antes de fevereiro de 2024, implementar um bot simples para o Viber podia ser feito gratuitamente em meia hora. Agora as regras são diferentes. O Viber passou os bots totalmente para uma base comercial; não se obtém um token sem uma candidatura oficial e um parceiro. Mas se já tem uma conta pública (ou se a está a configurar agora), a parte técnica, aqueles mesmos seis passos em PHP, manteve-se igual. Nós percorremos este caminho desde o token até ao teclado personalizado e mostramos cada passo.

💡 Visão geral rápida:

• Cria uma conta pública no Viber e obtém um token de autenticação: agora é passado no cabeçalho HTTP, e não no corpo do JSON
• Configura um webhook com um certificado HTTPS e escreve um manipulador em PHP para os pedidos de callback recebidos
• Implementa a receção de mensagens e o envio de respostas através da API de envio de mensagens: texto, imagens, ficheiros
• Adiciona um teclado personalizado com botões de resposta rápida e de link, a principal ferramenta de navegação dentro do bot
• Escreve código para a versão atual 7.3 da API REST do Viber, e não para guias desatualizados de 2017

Passo 1. Criar uma conta pública no Viber

O primeiro passo é obter uma conta pública (PA). Desde 5 de fevereiro de 2024, os bots são criados apenas numa base comercial através de parceiros oficiais da Rakuten Viber. O processo é o seguinte:

• Submete uma candidatura na página de contas públicas do Viber: tipo de negócio, cenários de utilização do bot.
• Após aprovação, chega um convite. Reinicia o dispositivo, vai ao ecrã principal das contas públicas e pressiona «Criar conta pública».
• Preenche os detalhes: nome, descrição, avatar. A sua conta principal do Viber é atribuída como administradora.

Como resultado, obtém uma conta pública e acesso às definições. É aqui que o token de autenticação aparece.

Os bots são suportados em iOS e Android a partir da versão 6.5 do Viber e superior, e em desktop a partir da versão 6.5.3. Se tiver uma versão antiga da aplicação, atualize-a antes de começar o desenvolvimento, caso contrário os teclados e alguns métodos da API não funcionarão.

Passo 2. Obter o token de autenticação

O token (chave de aplicação) é um identificador secreto único para o seu bot. Sem ele, nenhum pedido à API será bem-sucedido.

Após criar uma conta pública, o token fica disponível para o administrador na secção «Editar info» da conta pública. Uma forma alternativa é através do Painel de Administração do Viber. O token tem um aspeto semelhante a este:

455a0f2c05b4fe54-cb4e33d3200fbbae-95f29ebc06af09a8

Esta é uma chave de demonstração; a sua terá caracteres únicos, mas a mesma estrutura.

A principal alteração em comparação com os guias antigos: a partir da versão 7.0 da API, o token é passado não no corpo do pedido POST, mas no cabeçalho HTTP X-Viber-Auth-Token. Se enviar o token à maneira antiga, como um campo auth_token no JSON, a API devolverá um erro missing_auth_token.

Formato antigo (já não funciona):

1
{"auth_token": "your_token", "url": "https://..."}

Abordagem moderna, cabeçalho:

1
X-Viber-Auth-Token: your_token

Mantenha o token em segredo. Qualquer pessoa que o tenha pode enviar mensagens aos seus subscritores em nome do bot.

Passo 3. Configurar o webhook e escrever um manipulador em PHP

Um webhook é um URL no seu servidor para o qual o Viber envia pedidos de callback: mensagens de utilizadores, notificações de subscrição e outros eventos.

Requisitos do URL do webhook:

• Protocolo HTTPS com um certificado SSL válido de uma autoridade de certificação confiável. O Viber não suporta certificados autoassinados.
• O certificado deve estar na lista de confiança Sun Java; verifique antes de configurar.

A configuração do webhook é um pedido POST para https://chatapi.viber.com/pa/set_webhook. No cabeçalho X-Viber-Auth-Token, o seu token. Corpo do pedido:

1
{
2
  "url": "https://yourdomain.com/viber-webhook.php",
3
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"],
4
  "send_name": true,
5
  "send_photo": true
6
}

Parâmetros:

• url, o URL do seu webhook (obrigatório, HTTPS).
• event_types, eventos para callback. Obrigatórios e não filtráveis: message, subscribed e unsubscribed. Os restantes são opcionais.
• send_name e send_photo, se deve solicitar o nome e a foto do utilizador. Só funciona se o utilizador tiver ativado a «Personalização de conteúdo» nas definições de privacidade do Viber.

Enviamos o pedido via cURL:

1
<?php
2
 
3
$url = 'https://chatapi.viber.com/pa/set_webhook';
4
 
5
$jsonData = json_encode([
6
    'url' => 'https://yourdomain.com/viber-webhook.php',
7
    'event_types' => ['delivered', 'seen', 'failed', 'subscribed', 'unsubscribed', 'conversation_started'],
8
    'send_name' => true,
9
    'send_photo' => true
10
]);
11
 
12
$ch = curl_init($url);
13
curl_setopt($ch, CURLOPT_POST, 1);
14
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
15
curl_setopt($ch, CURLOPT_HTTPHEADER, [
16
    'Content-Type: application/json',
17
    'X-Viber-Auth-Token: your_auth_token'
18
]);
19
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
20
$result = curl_exec($ch);
21
curl_close($ch);
22
 
23
echo $result;

Após o envio, o Viber enviará um callback para o seu URL de webhook para verificar a disponibilidade. É esperada uma resposta HTTP 200. Dados do callback:

1
{
2
  "event": "webhook",
3
  "timestamp": 1457764197627,
4
  "message_token": 241256543215
5
}

O seu handler PHP deve devolver uma resposta:

1
{
2
  "status": 0,
3
  "status_message": "ok",
4
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started", "message"]
5
}

Código completo do handler do webhook, ficheiro viber-webhook.php no servidor:

1
<?php
2
 
3
$request = file_get_contents("php://input");
4
$input = json_decode($request, true);
5
 
6
if ($input['event'] == 'webhook') {
7
    $webhook_response['status'] = 0;
8
    $webhook_response['status_message'] = "ok";
9
    $webhook_response['event_types'] = 'delivered';
10
    echo json_encode($webhook_response);
11
    die;
12
}
13
elseif ($input['event'] == "subscribed") {
14
    // User subscribed — can send a welcome message
15
}
16
elseif ($input['event'] == "conversation_started") {
17
    // User opened chat — can send a menu
18
}
19
elseif ($input['event'] == "message") {
20
    $type = $input['message']['type'];
21
    $text = $input['message']['text'];
22
    $sender_id = $input['sender']['id'];
23
    $sender_name = $input['sender']['name'];
24
 
25
    // Form response
26
    $data = [
27
        'receiver' => $sender_id,
28
        'type' => 'text',
29
        'text' => "Hello, $sender_name! You wrote: $text",
30
        'sender' => [
31
            'name' => 'My Viber Bot'
32
        ]
33
    ];
34
 
35
    $ch = curl_init("https://chatapi.viber.com/pa/send_message");
36
    curl_setopt($ch, CURLOPT_POST, 1);
37
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
38
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
39
        'Content-Type: application/json',
40
        'X-Viber-Auth-Token: your_auth_token'
41
    ]);
42
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
43
    $result = curl_exec($ch);
44
    curl_close($ch);
45
}

Após a configuração bem-sucedida do webhook, aparecerá um botão de chat 1 para 1 no bot e os utilizadores poderão iniciar um diálogo. Para desativar esta opção, envie set_webhook com um url vazio.

Passo 4. Receber mensagens dos utilizadores

Quando um utilizador escreve para o bot, o Viber envia um callback para o seu webhook neste formato:

1
{
2
  "event": "message",
3
  "timestamp": 1457764197627,
4
  "message_token": 4912661846655238145,
5
  "sender": {
6
    "id": "01234567890A=",
7
    "name": "yarden",
8
    "avatar": "http://avatar_url"
9
  },
10
  "message": {
11
    "type": "text",
12
    "text": "a message to the service",
13
    "media": "http://download_url",
14
    "location": {
15
      "lat": 50.76891,
16
      "lon": 6.11499
17
    },
18
    "tracking_data": "tracking data"
19
  }
20
}

Campos principais a analisar:

O que é importante fazer no handler:

• Guarde a ligação sender.id → name/context na base de dados. A API do Viber não tem um método "obter todos os subscritores"; acumula os IDs por si próprio à medida que os pedidos chegam.
• Se o utilizador enviou uma imagem (type: "picture"), o URL do ficheiro está em message.media.
• Não ignore o tracking_data: ele liga a resposta do utilizador à sua mensagem enviada, sendo inestimável para análises de diálogo.

Passo 5. Enviar mensagens aos utilizadores

A API send_message suporta texto, imagens, vídeos, ficheiros, localizações, contactos, stickers, carrosséis e pré-visualizações de URL. Vamos abordar os tipos principais.

Mensagem de texto. Pedido POST para https://chatapi.viber.com/pa/send_message com o cabeçalho X-Viber-Auth-Token:

1
{
2
  "receiver": "01234567890A=",
3
  "type": "text",
4
  "text": "Hello! How can I help you?",
5
  "sender": {
6
    "name": "Support Bot"
7
  },
8
  "tracking_data": "welcome_message_001"
9
}

Envio de uma imagem:

1
{
2
  "receiver": "01234567890A=",
3
  "type": "picture",
4
  "text": "March 2026 promotion",
5
  "media": "https://yourdomain.com/img/promo.jpg",
6
  "thumbnail": "https://yourdomain.com/img/promo_thumb.jpg",
7
  "sender": {
8
    "name": "Shop Bot"
9
  }
10
}

• media, URL da imagem (apenas JPEG).
• thumbnail, URL da miniatura (também JPEG).
• text, descrição, pode ser null.

Função PHP para envio de mensagens, um wrapper universal que usamos na prática:

1
<?php
2
 
3
function sendViberMessage($receiverId, $type, $data, $trackingData = '') {
4
    $token = 'your_auth_token';
5
    $apiUrl = 'https://chatapi.viber.com/pa/send_message';
6
 
7
    $payload = array_merge(['receiver' => $receiverId, 'type' => $type], $data);
8
 
9
    if ($trackingData) {
10
        $payload['tracking_data'] = $trackingData;
11
    }
12
 
13
    $ch = curl_init($apiUrl);
14
    curl_setopt($ch, CURLOPT_POST, 1);
15
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
16
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
17
        'Content-Type: application/json',
18
        "X-Viber-Auth-Token: $token"
19
    ]);
20
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
21
    $result = curl_exec($ch);
22
    curl_close($ch);
23
 
24
    return json_decode($result, true);
25
}

Limitação: o tamanho máximo do pedido JSON é de 30 KB. Tenha isto em conta ao enviar carrosséis com muitos elementos.

Passo 6. Adicionar um teclado personalizado com botões

O teclado substitui o teclado padrão do dispositivo por um conjunto de botões: respostas rápidas, links para o site, transições para secções. Esta é a principal ferramenta de navegação dentro do bot.

O teclado é anexado a qualquer tipo de mensagem através do campo keyboard no pedido send_message:

1
{
2
  "receiver": "01234567890A=",
3
  "type": "text",
4
  "text": "What are you interested in?",
5
  "sender": {
6
    "name": "Help Bot"
7
  },
8
  "keyboard": {
9
    "Type": "keyboard",
10
    "BgColor": "#FFFFFF",
11
    "Buttons": [
12
      {
13
        "Columns": 6,
14
        "Rows": 1,
15
        "BgColor": "#2db9b9",
16
        "ActionType": "reply",
17
        "ActionBody": "Services",
18
        "Text": "📋 Services",
19
        "TextVAlign": "middle",
20
        "TextHAlign": "center",
21
        "TextSize": "regular"
22
      },
23
      {
24
        "Columns": 6,
25
        "Rows": 1,
26
        "BgColor": "#2db9b9",
27
        "ActionType": "open-url",
28
        "ActionBody": "https://yoursite.com/prices",
29
        "Text": "💰 Prices",
30
        "TextVAlign": "middle",
31
        "TextHAlign": "center",
32
        "TextSize": "regular"
33
      }
34
    ]
35
  }
36
}

Parâmetros do teclado:

Parâmetros para cada botão:

Algumas nuances importantes da prática:

• Um botão com ActionType: "open-url" abre o link num navegador externo, não dentro do Viber.
• Não sobrecarregue o teclado: 4 a 6 botões é o ideal para um ecrã.
• GIFs de fundo nos botões (BgMedia) suportam repetição contínua através de BgLoop: true.

A partir deste ponto, o bot está pronto a funcionar: recebe mensagens, responde com texto e imagens, mostra um teclado de menu.

Neste vídeo, uma demonstração ao vivo do ciclo completo: desde a criação de uma conta pública até ao envio da primeira mensagem com um teclado. Útil para ver antes de executar o código no seu próprio servidor.

⁉️🤔 Perguntas frequentes

É possível criar um bot Viber gratuitamente em 2026?

Não. Desde 5 de fevereiro de 2024, o Viber passou a criação de bots exclusivamente para termos comerciais. Para obter um token, precisa de contactar diretamente a Rakuten Viber ou um dos parceiros oficiais. Já não são emitidas contas de teste gratuitas. Os bots criados antes desta data continuam a funcionar.

É obrigatório usar PHP para um bot Viber?

Não, a linguagem não importa. A API do Viber funciona através de pedidos HTTP POST/GET, qualquer backend serve: Node.js, Python, Go, Ruby. Mostramos PHP por ser a linguagem mais comum em alojamentos WordPress e servidores partilhados, disponível para a maioria dos proprietários de sites sem configuração adicional de ambiente.

Como verifico se o webhook está a funcionar?

Após chamar set_webhook, o Viber envia imediatamente um callback com "event": "webhook" para o seu URL. O servidor devolve HTTP 200, o webhook fica ativo. Pode verificar o estado atual com uma nova chamada set_webhook com os mesmos parâmetros; a resposta da API mostrará os event_types registados. Para depuração, utilize o registo de file_get_contents("php://input") para um ficheiro no servidor.

Qual é a diferença entre o método de autenticação antigo e o novo?

Antes da versão 7.0 da API, o token era passado no corpo JSON de cada pedido como o campo auth_token. A API moderna (7.0+) exige a passagem do token no cabeçalho HTTP X-Viber-Auth-Token. O formato antigo não é suportado; pedidos com auth_token no corpo devolvem um erro missing_auth_token. Se estiver a migrar código de guias de 2017-2023, substitua a passagem do token por um cabeçalho.

O que fazer se o utilizador não vir o teclado?

Três causas prováveis: (1) o pedido JSON excedeu o limite de 30 KB, reduza o número de botões ou remova media de fundo; (2) o campo Type contém algo diferente de "keyboard", este é o único valor suportado; (3) o utilizador está numa versão antiga do Viber, os teclados são suportados a partir da versão 6.5.

Posso eliminar o webhook e desativar o chat 1 para 1?

Sim, envie set_webhook com uma string vazia em url:

1
{"url": ""}

O botão de chat desaparecerá, mas o token e a conta pública serão preservados. Útil quando se move um bot para outro servidor.

O que escolher em 2026: o seu próprio bot PHP ou uma plataforma sem código

Se leu até aqui, tem dois caminhos pela frente. O primeiro é escrever um bot em PHP seguindo os passos acima. Obtém controlo total sobre a lógica, os dados e o alojamento. Adequado quando o bot faz parte de um projeto maior: loja online, serviço de apoio, ferramenta interna de equipa.

O segundo caminho são as plataformas sem código como SendPulse, Infobip ou Kommunicate. Elas tratam da infraestrutura do webhook e fornecem um editor visual para cenários. O preço é uma subscrição mensal e limitações do plano gratuito. Para tarefas típicas como respostas automáticas de FAQ, envios promocionais, isto é mais do que suficiente.

Na prática, costumamos combinar: o núcleo do bot em PHP para lógica personalizada, e montamos teclados e cadeias de boas-vindas no editor visual da plataforma, mais rápido e mais visual. Escolha o que estiver mais próximo das suas competências e da sua tarefa. Comece hoje pelo primeiro passo, uma conta pública configura-se em meia hora, e depois cada passo seguinte demora exatamente o tempo necessário para copiar e adaptar o código deste guia.