Concepts fondamentaux

​

Pourquoi cette page existe

• qu’est-ce qu’une instance ?
• quelle différence entre instanceId, name et waNumber ?
• qu’est-ce qu’une clé API ?
• qu’est-ce qu’un webhook ?
• qu’est-ce qu’un payload ?

​

Vue d’ensemble

• votre compte MsgFlash
• votre ou vos numéros WhatsApp connectés
• vos intégrations techniques comme votre backend, WordPress, Zapier ou d’autres outils

1. vous créez une instance WhatsApp
2. vous connectez un vrai numéro WhatsApp à cette instance
3. vous créez une clé API
4. votre code utilise cette clé pour appeler l’API MsgFlash
5. MsgFlash envoie le message via l’instance choisie

​

Instance WhatsApp

​

Définition simple

• brancher un téléphone à la plateforme
• ou connecter WhatsApp Web à un outil d’automatisation

​

Exemple concret

• votre boutique e-commerce
• votre support client

• une instance Boutique principale
• une instance Support

​

Ce qu’une instance n’est pas

• un utilisateur
• une clé API
• un template
• une campagne

​

instanceId, name et waNumber

​

instanceId

• envoyer un message
• planifier un message
• créer une campagne
• publier un statut
• lancer certaines opérations comme les number lookups

d6f66e76-9e59-41a5-bba8-a45c7fb72bfc

​

name

Boutique principale

​

waNumber

2250715516311

​

Règle essentielle

​

Exemple réel

{
  "data": [
    {
      "id": "d6f66e76-9e59-41a5-bba8-a45c7fb72bfc",
      "name": "Boutique principale",
      "waNumber": "2250715516311",
      "status": "connected"
    }
  ]
}

• id = la valeur à utiliser comme instanceId
• name = le nom affiché à l’écran
• waNumber = le numéro WhatsApp relié à cette instance

​

Comment obtenir le bon instanceId

1. appelez GET /api/v1/instances
2. choisissez l’instance voulue
3. récupérez data[n].id
4. utilisez cette valeur dans vos appels

{
  "instanceId": "d6f66e76-9e59-41a5-bba8-a45c7fb72bfc",
  "to": "+2250715516311",
  "type": "text",
  "text": "Bonjour"
}

​

Erreur classique à éviter

{
  "instanceId": "Boutique principale"
}

{
  "instanceId": "2250715516311"
}

​

Clé API

​

Définition simple

• un mot de passe machine-à-machine
• une carte d’accès pour vos appels API

​

Exemple

msgf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​

À quoi elle sert

• authentifier vos requêtes
• savoir à quel compte elles appartiennent
• appliquer vos quotas et limites

​

Où elle s’utilise

x-api-key: msgf_live_...

​

Ce qu’il ne faut jamais faire

• ne pas l’exposer dans du JavaScript public côté navigateur
• ne pas la committer dans Git
• ne pas l’envoyer dans un frontend non sécurisé

​

Webhook

​

Définition simple

• message délivré
• message lu
• message reçu
• statut d’instance modifié

​

Image mentale

• votre système doit demander en boucle “est-ce qu’il s’est passé quelque chose ?”

• MsgFlash vous prévient directement

​

Exemple

https://mon-app.com/webhooks/msgflash

​

Campagne

​

Définition simple

• une promo
• une relance
• une newsletter WhatsApp
• une communication segmentée

​

Important

• une instance
• une date/heure
• une audience
• un contenu

​

Exemple

• Bonjour {{contact.name}}, votre panier vous attend encore.

• tous les contacts tagués panier-abandonne

​

Scheduled message

​

Définition simple

• vous créez un message à 9h
• vous demandez qu’il parte à 18h

​

Différence avec une campagne

• message planifié : un seul destinataire
• campagne : plusieurs destinataires

​

QR Code

​

Définition simple

​

Comment ça marche

1. vous créez une instance
2. MsgFlash affiche un QR code
3. vous le scannez avec WhatsApp sur votre téléphone
4. le numéro est connecté à la plateforme

​

Ce que ça ne fait pas

​

Quota

​

Définition simple

• nombre de messages par mois
• nombre de requêtes API par mois
• nombre d’instances
• nombre de clés API

​

Exemple concret

• 20 messages mensuels

• 12

• 8

​

Important

​

Payload

​

Définition simple

• c’est le corps JSON d’une requête ou d’une notification

​

Exemple de payload d’envoi

{
  "instanceId": "d6f66e76-9e59-41a5-bba8-a45c7fb72bfc",
  "to": "+2250715516311",
  "type": "text",
  "text": "Bonjour"
}

​

Exemple de payload webhook

{
  "event": "message.delivered",
  "data": {
    "messageId": "msg_uuid",
    "status": "delivered"
  }
}

​

Template

​

Définition simple

• du texte
• parfois un média
• des variables dynamiques

​

Exemple

Bonjour {{contact.name}}, votre commande {{custom.orderId}} a été validée.

​

Contact

​

Définition simple

• un nom
• un téléphone
• des tags
• des groupes

• les campagnes
• les segments
• les imports CSV

​

Groupe de contacts

​

Définition simple

• Clients VIP
• Panier abandonné
• Support premium

​

Différence entre API publique et dashboard

​

Dashboard

• connecter WhatsApp
• créer les instances
• gérer la facturation
• gérer les clés API
• gérer les contacts, templates et campagnes

​

API publique

• envoyer des messages depuis votre code
• lire vos ressources
• créer des campagnes
• automatiser votre intégration

• dashboard = configuration et pilotage
• API = automatisation

​

Scénario complet simple

1. créer un compte MsgFlash
2. créer une instance WhatsApp
3. connecter le numéro via QR code
4. générer une clé API
5. appeler GET /api/v1/instances
6. récupérer data[0].id
7. utiliser cette valeur comme instanceId
8. envoyer un message avec POST /api/v1/messages/send

​

Résumé ultra-court

• instance WhatsApp = un numéro connecté à MsgFlash
• instanceId = l’identifiant technique à envoyer à l’API
• name = le nom lisible de l’instance
• waNumber = le vrai numéro connecté
• clé API = le secret pour appeler l’API
• webhook = l’URL que MsgFlash appelle pour te notifier
• campagne = un envoi à plusieurs contacts
• scheduled message = un message prévu pour plus tard
• quota = ta limite d’usage
• payload = le JSON envoyé ou reçu

​

Aller plus loin

• Démarrage rapide
• Guide: Instances
• Guide: Envoyer un message
• Guide: Webhooks