Un utilisateur écrit sur Viber, et personne ne répond. Un scénario familier pour les petites entreprises: un seul responsable, trois messageries, et les clients s’en vont vers ceux qui ont répondu en premier. Un chatbot résout ce problème de manière radicale: il travaille 24 heures sur 24, ne se fatigue pas et réagit instantanément.

Auparavant, avant février 2024, déployer un bot Viber simple pouvait se faire gratuitement en une demi-heure. Désormais, les règles ont changé. Viber a fait passer tous les bots sur une base commerciale, vous ne pouvez pas obtenir de jeton sans une demande officielle et un partenaire. Mais si vous avez déjà un compte public (ou que vous le configurez en ce moment même), la partie technique, ces six mêmes étapes en PHP, est restée identique. Nous avons parcouru ce chemin, du jeton au clavier personnalisé, et nous vous montrons chaque étape.

💡 Aperçu rapide:

• Vous créez un compte public Viber et obtenez un jeton d’authentification: désormais, il est transmis dans l’en-tête HTTP, et non dans le corps JSON
• Vous configurez un webhook avec un certificat HTTPS et écrivez un gestionnaire PHP pour les requêtes de rappel entrantes
• Vous implémentez la réception de messages et l’envoi de réponses via l’API d’envoi de message: texte, images, fichiers
• Vous ajoutez un clavier personnalisé avec des boutons de réponse rapide et de lien, l’outil de navigation principal à l’intérieur du bot
• Vous écrivez le code pour la version actuelle 7.3 de l’API REST de Viber, et non pour des guides obsolètes de 2017

Étape 1. Créer un compte public Viber

La première étape consiste à obtenir un compte public (CP). Depuis le 5 février 2024, les bots sont créés uniquement sur une base commerciale via les partenaires officiels de Rakuten Viber. Le processus se déroule comme suit:

• Vous soumettez une demande sur la page des comptes publics Viber: type d’activité, scénarios d’utilisation du bot.
• Après approbation, une invitation arrive. Vous redémarrez votre appareil, allez sur l’écran principal des comptes publics et appuyez sur «Créer un compte public».
• Vous remplissez les informations: nom, description, avatar. Votre compte Viber principal est désigné comme administrateur.

Vous obtenez ainsi un compte public et l’accès aux paramètres. C’est là qu’apparaît le jeton d’authentification.

Les bots sont pris en charge sur iOS et Android à partir de la version 6.5 de Viber, et sur ordinateur, à partir de la version 6.5.3. Si vous avez une ancienne version de l’application, mettez-la à jour avant de commencer le développement, sinon les claviers et certaines méthodes de l’API ne fonctionneront pas.

Étape 2. Obtenir le jeton d’authentification

Le jeton (clé d’application) est un identifiant secret unique pour votre bot. Sans lui, aucune requête API ne pourra aboutir.

Après la création d’un compte public, le jeton est accessible à l’administrateur dans la section «Modifier les infos» du compte public. Une autre méthode consiste à passer par le Panneau d’administration Viber. Le jeton ressemble à ceci:

455a0f2c05b4fe54-cb4e33d3200fbbae-95f29ebc06af09a8

Ceci est une clé de démonstration, la vôtre aura des caractères uniques mais la même structure.

Le principal changement par rapport aux anciens guides: à partir de la version 7.0 de l’API, le jeton est transmis non pas dans le corps de la requête POST, mais dans l’en-tête HTTP X-Viber-Auth-Token. Si vous envoyez le jeton à l’ancienne manière, en tant que champ auth_token dans le JSON, l’API renverra une erreur missing_auth_token.

Ancien format (ne fonctionne plus):

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

Approche moderne, en-tête:

1
X-Viber-Auth-Token: your_token

Gardez le jeton secret. Toute personne qui le détient peut envoyer des messages à vos abonnés au nom du bot.

Étape 3. Configurer le webhook et écrire un gestionnaire PHP

Un webhook est une URL sur votre serveur vers laquelle Viber envoie des requêtes de rappel: messages des utilisateurs, notifications d’abonnement et autres événements.

Exigences relatives à l’URL du webhook:

• Protocole HTTPS avec un certificat SSL valide émis par une autorité de certification de confiance. Viber ne prend pas en charge les certificats auto-signés.
• Le certificat doit figurer dans la liste de confiance Sun Java, vérifiez-le avant la configuration.

La configuration du webhook consiste en une requête POST vers https://chatapi.viber.com/pa/set_webhook. Dans l’en-tête X-Viber-Auth-Token, votre jeton. Corps de la requête:

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
}

Paramètres:

• url, l’URL de votre webhook (obligatoire, HTTPS).
• event_types, les événements pour le rappel. Obligatoires et non filtrables: message, subscribed et unsubscribed. Les autres sont optionnels.
• send_name et send_photo, pour demander ou non le nom et la photo de l’utilisateur. Fonctionne uniquement si l’utilisateur a activé la «Personnalisation du contenu» dans les paramètres de confidentialité de Viber.

Nous envoyons la requête 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;

Après l’envoi, Viber adresse un callback à votre URL de webhook pour en vérifier la disponibilité. Une réponse HTTP 200 est attendue. Données du callback:

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

Votre gestionnaire PHP doit renvoyer une réponse:

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

Code complet du gestionnaire de webhook, fichier viber-webhook.php sur le serveur:

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
}

Une fois le webhook configuré avec succès, un bouton de chat 1-à-1 apparaîtra dans le bot et les utilisateurs pourront engager une conversation. Pour désactiver cette option, envoyez set_webhook avec une url vide.

Étape 4. Recevoir les messages des utilisateurs

Lorsqu’un utilisateur écrit au bot, Viber envoie un callback à votre webhook dans ce format:

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
}

Champs clés à analyser:

Ce qu’il est important de faire dans le gestionnaire:

• Enregistrez le lien sender.id → name/context en base de données. L’API Viber ne propose pas de méthode «obtenir tous les abonnés», vous accumulez vous-même les identifiants au fil des requêtes.
• Si l’utilisateur a envoyé une image (type: "picture"), l’URL du fichier se trouve dans message.media.
• Ne négligez pas tracking_data: ce champ relie la réponse de l’utilisateur à votre message sortant, ce qui est précieux pour l’analyse des conversations.

Étape 5. Envoyer des messages aux utilisateurs

L’API send_message prend en charge le texte, les images, les vidéos, les fichiers, les localisations, les contacts, les stickers, les carrousels et les aperçus d’URL. Passons en revue les principaux types.

Message texte. Requête POST vers https://chatapi.viber.com/pa/send_message avec l’en-tête 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
}

Envoi d’une image:

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 l’image (JPEG uniquement).
• thumbnail, URL de la vignette (également en JPEG).
• text, description, peut être null.

Fonction PHP pour l’envoi de messages, un wrapper universel que nous utilisons en pratique:

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
}

Limitation: la taille maximale d'une requête JSON est de 30 Ko. Tenez-en compte lorsque vous envoyez des carrousels contenant de nombreux éléments.

Étape 6. Ajouter un clavier personnalisé avec des boutons

Le clavier remplace le clavier standard de l’appareil par un ensemble de boutons: réponses rapides, liens vers le site, transitions vers des sections. C’est l’outil de navigation principal à l’intérieur du bot.

Le clavier est attaché à tout type de message via le champ keyboard dans la requête 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
}

Paramètres du clavier:

Paramètres pour chaque bouton:

Quelques nuances importantes issues de la pratique:

• Un bouton avec ActionType: "open-url" ouvre le lien dans un navigateur externe, pas à l’intérieur de Viber.
• Ne surchargez pas le clavier: 4 à 6 boutons est optimal pour un écran.
• Les GIF d’arrière-plan dans les boutons (BgMedia) prennent en charge la lecture en boucle via BgLoop: true.

À partir de ce point, le bot est prêt à fonctionner: il reçoit des messages, répond avec du texte et des images, affiche un clavier de menu.

Dans cette vidéo, une démonstration en direct du cycle complet: de la création d’un compte public à l’envoi du premier message avec un clavier. Utile à regarder avant d’exécuter le code sur votre propre serveur.

⁉️🤔 Foire aux questions

Est-il possible de créer un bot Viber gratuitement en 2026?

Non. Depuis le 5 février 2024, Viber a basculé la création de bots exclusivement vers des conditions commerciales. Pour obtenir un token, vous devez contacter directement Rakuten Viber ou l’un des partenaires officiels. Les comptes de test gratuits ne sont plus délivrés. Les bots créés avant cette date continuent de fonctionner.

Est-il obligatoire d’utiliser PHP pour un bot Viber?

Non, le langage n’a pas d’importance. L’API Viber fonctionne via des requêtes HTTP POST/GET, n’importe quel backend convient: Node.js, Python, Go, Ruby. Nous montrons PHP parce que c’est le langage le plus répandu sur les hébergements WordPress et les serveurs mutualisés, accessible à la plupart des propriétaires de sites sans configuration d’environnement supplémentaire.

Comment vérifier que le webhook fonctionne?

Après l’appel à set_webhook, Viber envoie immédiatement un callback avec "event": "webhook" vers votre URL. Le serveur retourne HTTP 200, le webhook est actif. Vous pouvez vérifier l’état actuel en rappelant set_webhook avec les mêmes paramètres, la réponse de l’API affichera les event_types enregistrés. Pour le débogage, utilisez la journalisation de file_get_contents("php://input") dans un fichier sur le serveur.

Quelle est la différence entre l’ancienne méthode d’authentification et la nouvelle?

Avant la version 7.0 de l’API, le token était transmis dans le corps JSON de chaque requête via le champ auth_token. L’API moderne (7.0+) exige de transmettre le token dans l’en-tête HTTP X-Viber-Auth-Token. L’ancien format n’est pas pris en charge, les requêtes avec auth_token dans le corps renvoient une erreur missing_auth_token. Si vous migrez du code issu de guides de 2017-2023, remplacez la transmission du token par un en-tête.

Que faire si l’utilisateur ne voit pas le clavier?

Trois causes probables: (1) la requête JSON a dépassé la limite de 30 Ko, réduisez le nombre de boutons ou supprimez les médias d’arrière-plan; (2) le champ Type contient autre chose que "keyboard", c’est la seule valeur prise en charge; (3) l’utilisateur utilise une ancienne version de Viber, les claviers sont pris en charge à partir de la version 6.5.

Puis-je supprimer le webhook et désactiver la discussion 1-à-1?

Oui, envoyez set_webhook avec une chaîne vide dans url:

1
{"url": ""}

Le bouton de discussion disparaîtra, mais le token et le compte public seront conservés. Utile lors du déplacement d’un bot vers un autre serveur.

Que choisir en 2026: votre propre bot PHP ou une plateforme no-code

Si vous avez lu jusqu’ici, deux voies s’offrent à vous. La première consiste à écrire un bot en PHP en suivant les étapes ci-dessus. Vous obtenez un contrôle total sur la logique, les données et l’hébergement. C’est adapté lorsque le bot fait partie d’un projet plus vaste: boutique en ligne, service d’assistance, outil interne d’équipe.

La seconde voie, ce sont les plateformes no-code comme SendPulse, Infobip ou Kommunicate. Elles prennent en charge l’infrastructure du webhook et fournissent un éditeur visuel pour les scénarios. Le prix est un abonnement mensuel et les limitations des offres gratuites. Pour des tâches typiques comme les réponses automatiques de FAQ ou les envois promotionnels, c’est largement suffisant.

En pratique, nous combinons généralement les deux: le cœur du bot en PHP pour la logique personnalisée, et nous assemblons les claviers et les chaînes de bienvenue dans l’éditeur visuel de la plateforme, c’est plus rapide et plus visuel. Choisissez ce qui correspond le mieux à vos compétences et à votre besoin. Commencez dès aujourd’hui par la première étape, un compte public se configure en une demi-heure, et chaque étape suivante prend exactement le temps qu’il faut pour copier et adapter le code de ce guide.