Un usuario escribe por Viber y nadie responde. Un escenario familiar para los pequeños negocios: un solo gestor, tres mensajerías y los clientes se van con quien respondió primero. Un chatbot resuelve este problema de raíz: trabaja las 24 horas, no se cansa y reacciona al instante.

Antes, hasta febrero de 2024, desplegar un bot sencillo de Viber podía hacerse gratis en media hora. Ahora las reglas son distintas. Viber ha pasado los bots por completo a un modelo comercial: no se puede obtener un token sin una solicitud oficial y un partner. Pero si usted ya tiene una cuenta pública (o la está configurando ahora mismo), la parte técnica, esos mismos seis pasos en PHP, sigue siendo igual. Nosotros recorrimos este camino desde el token hasta el teclado personalizado y le mostramos cada paso.

💡 Resumen rápido:

• Usted crea una cuenta pública de Viber y obtiene un token de autenticación: ahora se envía en la cabecera HTTP, no en el cuerpo JSON
• Configura un webhook con un certificado HTTPS y escribe un manejador PHP para las solicitudes entrantes de callback
• Implementa la recepción de mensajes y el envío de respuestas mediante la API de envío de mensajes: texto, imágenes, archivos
• Añade un teclado personalizado con botones de respuesta rápida y enlaces, la principal herramienta de navegación dentro del bot
• Escribe código para la versión actual 7.3 de la API REST de Viber, no para guías obsoletas de 2017

Paso 1. Crear una cuenta pública de Viber

El primer paso es obtener una cuenta pública (PA, por sus siglas en inglés). Desde el 5 de febrero de 2024, los bots se crean solo de forma comercial a través de los partners oficiales de Rakuten Viber. El proceso es el siguiente:

• Usted envía una solicitud en la página de cuentas públicas de Viber: tipo de negocio, escenarios de uso del bot.
• Tras la aprobación, llega una invitación. Reinicie su dispositivo, vaya a la pantalla principal de cuentas públicas y pulse «Crear cuenta pública».
• Rellene los datos: nombre, descripción, avatar. Su cuenta principal de Viber se asigna como administradora.

Como resultado, obtiene una cuenta pública y acceso a la configuración. Aquí es donde aparece el token de autenticación.

Los bots son compatibles en iOS y Android a partir de la versión 6.5 de Viber, y en escritorio desde la versión 6.5.3. Si tiene una versión antigua de la aplicación, actualícela antes de empezar el desarrollo; de lo contrario, los teclados y algunos métodos de la API no funcionarán.

Paso 2. Obtener el token de autenticación

El token (clave de aplicación) es un identificador secreto único de su bot. Sin él, ninguna solicitud a la API tendrá éxito.

Tras crear una cuenta pública, el token está disponible para el administrador en la sección «Editar información» de la cuenta pública. Una vía alternativa es a través del Panel de Administración de Viber. El token tiene un aspecto similar a este:

455a0f2c05b4fe54-cb4e33d3200fbbae-95f29ebc06af09a8

Esta es una clave de demostración; la suya tendrá caracteres únicos, pero la misma estructura.

El principal cambio respecto a las guías antiguas: a partir de la versión 7.0 de la API, el token se envía no en el cuerpo de la solicitud POST, sino en la cabecera HTTP X-Viber-Auth-Token. Si envía el token a la antigua usanza, como un campo auth_token en el JSON, la API devolverá un error missing_auth_token.

Formato antiguo (ya no funciona):

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

Enfoque moderno, por cabecera:

1
X-Viber-Auth-Token: your_token

Mantenga el token en secreto. Cualquiera que lo tenga puede enviar mensajes a sus suscriptores en nombre del bot.

Paso 3. Configurar el webhook y escribir un manejador PHP

Un webhook es una URL en su servidor a la que Viber envía solicitudes de callback: mensajes de usuarios, notificaciones de suscripción y otros eventos.

Requisitos de la URL del webhook:

• Protocolo HTTPS con un certificado SSL válido de una autoridad de certificación de confianza. Viber no admite certificados autofirmados.
• El certificado debe estar en la lista de confianza de Sun Java; compruébelo antes de la configuración.

La configuración del webhook es una solicitud POST a https://chatapi.viber.com/pa/set_webhook. En la cabecera X-Viber-Auth-Token, su token. Cuerpo de la solicitud:

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, la URL de su webhook (obligatorio, HTTPS).
• event_types, eventos para el callback. Obligatorios y no filtrables: message, subscribed y unsubscribed. El resto son opcionales.
• send_name y send_photo, si se solicita el nombre y la foto del usuario. Solo funciona si el usuario ha activado «Personalización de contenido» en los ajustes de privacidad de Viber.

Enviamos la solicitud mediante 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;

Tras el envío, Viber enviará un callback a la URL de su webhook para verificar la disponibilidad. Se espera una respuesta HTTP 200. Datos del callback:

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

Su manejador PHP debe devolver una respuesta:

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

Código completo del manejador del webhook, archivo viber-webhook.php en el 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
}

Tras una configuración exitosa del webhook, aparecerá un botón de chat 1 a 1 en el bot y los usuarios podrán iniciar un diálogo. Para desactivar esta opción, envíe set_webhook con una url vacía.

Paso 4. Recibir mensajes de los usuarios

Cuando un usuario escribe al bot, Viber envía un callback a su webhook con este 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 clave que debe interpretar:

Qué es importante hacer en el manejador:

• Guarde el enlace sender.id → name/context en la base de datos. La API de Viber no tiene un método «obtener todos los suscriptores»: usted acumula los IDs por su cuenta a medida que llegan las solicitudes.
• Si el usuario envió una imagen (type: "picture"), la URL del archivo está en message.media.
• No ignore tracking_data: vincula la respuesta del usuario con su mensaje saliente, algo muy valioso para la analítica de diálogos.

Paso 5. Enviar mensajes a los usuarios

La API send_message admite texto, imágenes, videos, archivos, ubicaciones, contactos, stickers, carruseles y vistas previas de URL. Cubramos los tipos principales.

Mensaje de texto. Solicitud POST a https://chatapi.viber.com/pa/send_message con el encabezado 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
}

Envío de una imagen:

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 de la imagen (solo JPEG).
• thumbnail, URL de la miniatura (también JPEG).
• text, descripción, puede ser null.

Función PHP para enviar mensajes, un envoltorio universal que usamos en la práctica:

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
}

Limitación: el tamaño máximo de la solicitud JSON es de 30 KB. Tenga esto en cuenta al enviar carruseles con muchos elementos.

Paso 6. Añadir un teclado personalizado con botones

El teclado reemplaza el teclado estándar del dispositivo por un conjunto de botones: respuestas rápidas, enlaces al sitio, transiciones a secciones. Esta es la principal herramienta de navegación dentro del bot.

El teclado se adjunta a cualquier tipo de mensaje mediante el campo keyboard en la solicitud 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 del teclado:

Parámetros para cada botón:

Algunos matices importantes desde la práctica:

• Un botón con ActionType: "open-url" abre el enlace en un navegador externo, no dentro de Viber.
• No sobrecargue el teclado: de 4 a 6 botones es lo óptimo para una pantalla.
• Los GIF de fondo en los botones (BgMedia) admiten repetición en bucle mediante BgLoop: true.

A partir de este punto, el bot está listo para funcionar: recibe mensajes, responde con texto e imágenes, muestra un teclado de menú.

En este video, una demostración en vivo del ciclo completo: desde la creación de una cuenta pública hasta el envío del primer mensaje con un teclado. Útil de ver antes de ejecutar el código en su propio servidor.

⁉️🤔 Preguntas frecuentes

¿Es posible crear un bot de Viber gratis en 2026?

No. Desde el 5 de febrero de 2024, Viber ha trasladado la creación de bots exclusivamente a términos comerciales. Para obtener un token, debe contactar directamente con Rakuten Viber o con uno de los socios oficiales. Ya no se emiten cuentas de prueba gratuitas. Los bots creados antes de esta fecha continúan funcionando.

¿Es obligatorio usar PHP para un bot de Viber?

No, el lenguaje no importa. La API de Viber funciona mediante solicitudes HTTP POST/GET, cualquier backend sirve: Node.js, Python, Go, Ruby. Mostramos PHP porque es el lenguaje más común en alojamientos WordPress y servidores compartidos, disponible para la mayoría de los propietarios de sitios sin configuración adicional del entorno.

¿Cómo verifico que el webhook está funcionando?

Después de llamar a set_webhook, Viber envía inmediatamente una devolución de llamada con "event": "webhook" a su URL. El servidor devuelve HTTP 200, el webhook está activo. Puede verificar el estado actual con una llamada repetida a set_webhook con los mismos parámetros, la respuesta de la API mostrará los event_types registrados. Para depuración, use el registro de file_get_contents("php://input") en un archivo en el servidor.

¿Cuál es la diferencia entre el método de autenticación antiguo y el nuevo?

Antes de la versión 7.0 de la API, el token se pasaba en el cuerpo JSON de cada solicitud como el campo auth_token. La API moderna (7.0+) requiere pasar el token en el encabezado HTTP X-Viber-Auth-Token. El formato antiguo no es compatible, las solicitudes con auth_token en el cuerpo devuelven un error missing_auth_token. Si está migrando código de guías de 2017-2023, reemplace el paso del token por un encabezado.

¿Qué hacer si el usuario no ve el teclado?

Tres causas probables: (1) la solicitud JSON superó el límite de 30 KB, reduzca el número de botones o elimine los medios de fondo; (2) el campo Type contiene algo distinto de "keyboard", este es el único valor admitido; (3) el usuario tiene una versión antigua de Viber, los teclados son compatibles a partir de la versión 6.5.

¿Puedo eliminar el webhook y desactivar el chat uno a uno?

Sí, envíe set_webhook con una cadena vacía en url:

1
{"url": ""}

El botón de chat desaparecerá, pero el token y la cuenta pública se conservarán. Útil al trasladar un bot a otro servidor.

Qué elegir en 2026: su propio bot PHP o una plataforma sin código

Si ha leído hasta aquí, tiene dos caminos por delante. El primero es escribir un bot en PHP siguiendo los pasos anteriores. Obtiene control total sobre la lógica, los datos y el alojamiento. Adecuado cuando el bot es parte de un proyecto más grande: tienda en línea, servicio de soporte, herramienta interna de equipo.

El segundo camino son las plataformas sin código como SendPulse, Infobip o Kommunicate. Ellas gestionan la infraestructura del webhook y proporcionan un editor visual para escenarios. El precio es una suscripción mensual y limitaciones del nivel gratuito. Para tareas típicas como respuestas automáticas de preguntas frecuentes, envíos promocionales, esto es más que suficiente.

En la práctica, solemos combinar: el núcleo del bot en PHP para la lógica personalizada, y ensamblamos teclados y cadenas de bienvenida en el editor visual de la plataforma, más rápido y visual. Elija lo que se ajuste mejor a sus habilidades y tarea. Comience hoy con el primer paso, una cuenta pública se configura en media hora, y luego cada paso siguiente toma exactamente el tiempo que lleva copiar y adaptar el código de esta guía.