Whatsapp Documentation

Dernière mise à jour: Jeudi 14 septembre 2023

Start HSM

Lance une conversation en envoyant un premier message (HSM).
HSM : ce sont des modèles prédéfinis validés par WhatsApp. Avant de les utiliser dans vos applications, assurez-vous de disposer de modèles validés sur votre compte. Vous pouvez également les créer directement depuis l'API.

POST : https://app.sparrowmessage.com/api/v2/whatsapp/send/hsm

Headers :
# Key Value
1 Accept application/json
2 Content-Type application/json
3 Authorization Bearer {api_token}

api_token : récupérable à partir du service d'authentification vérifier ici


Params :
# Paramètre Type Description
1 phone string Le destinataire
2 hsm string Le nom du modèle HSM
3 params Table Table de paramètres à utiliser pour le modèle HSM (1)
4 verification_code int Code de vérification - Cas de l'authentification(2)

(1) : : L'ordre des paramètres est important

(2) : : Code de vérification requis, sauf pour les templates de type AUTHENTICATION.

Si le modèle inclut des médias (image, vidéo, document) ou le type "texte", vous avez la possibilité d'ajouter les paramètres suivants :

# Paramètre Type Description
1 image_url string URL d'une image à inclure dans le message.
2 video_url string URL d'une vidéo à inclure dans le message.
3 document_url string URL d'un document à inclure dans le message.
3 title string Titre à inclure dans le message.
Response :
{
    "code": "OK/KO",
    "conversation": "object", // SI code "OK"
    "error": "string" // Si code "KO"
}

Send Message

L'envoi d'un message libre doit toujours être effectué sur une conversation active (1).

POST : https://app.sparrowmessage.com/api/v2/whatsapp/send/message

Headers :
# Key Value
1 Accept application/json
2 Content-Type application/json
3 Authorization Bearer {api_token}

api_token : récupérable à partir du service d'authentification vérifier ici


Params :
# Paramètre Type Description
1 conversation int ID de conversation
2 phone string Le destinataire
3 type string Le type de message (2)
4 content Content Objet du contenu à envoyer (3)

(1) : : une conversation active est une conversation commençant par un HSM avec un retour du destinataire ou démarrée par le destinataire directement sur votre numéro de téléphone utilisé pour Whatsapp, et le retour du destinataire ne date pas de plus de 24 heures
(2) : : Type de message possible sont : audio file image location text Interaction
(3) : : "Content" change selon le type de message envoyé, voir le tableau ci-dessous pour plus de détails

"Content" Objet :
# Type Params
1 audio url
2 file url, file_name
3 image url, text
4 location latitude, longitude
5 text text
6 interactive header_text, body_text, footer, button_text, list_title, sections
sections:
- title - rows - id - title
Example de Message Interactive :
{
    "conversation": "873",
    "phone": "21266666666",
    "type": "interactive",
    "content": {
        "header_text": "Liste produits",
        "body_text": "Les produits Disponible",
        "footer": "E-solution",
        "button_text": "Liste produits",
        "list_title": "Categories",
        "sections": [
            {
                "title": "Categories",
                "rows": [
                    {"id": "10", "title": "First Choice"}
                ]
            }
        ]
    }
}
Response :
{
    "code": "OK/KO",
    "conversation": "object", // SI code "OK"
    "error": "string" // Si code "KO"
}

Setup Webhook

Les webhooks permettent de fournir des notifications en temps réel des événements de conversation aux points de terminaison sur votre propre serveur. Un webhook peut être configuré avec une URL. Il est possible de créer plusieurs webhooks avec différentes URL pour écouter chacun un ou plusieurs événements.

pour vous montrer comment ajouter votre webhook nous vous proposons les images suivantes

#
...

#
...

#
...

Gérer les webhooks :

Des requêtes HTTP seront adressées à votre plateforme à l'URL fournie avec votre webhook chaque fois qu'un des événements est déclenché, chaque événement a une charge utile spécifique qui vous est livrée sous forme de requête POST.

Example JSON bodies are provided below:

conversation.created event 
{
  "type": "conversation.created",
  "contact": {
    "id": "5056",
    "phone": 316123456789,
    "nom": "Jen",
    "prenom": "Smith"
  },
  "conversation": {
    "id": "1084",
    "status": "active"
  }
}
conversation.updated event 
{
  "type": "conversation.updated",
  "contact": {
    "id": "5056",
    "phone": 316123456789,
    "nom": "Jen",
    "prenom": "Smith"
  },
  "conversation": {
    "id": "1084",
    "status": "active"
  }
}
message.created event 
{
  "type": "message.created",
  "contact": {
    "id": "5056",
    "phone": 316123456789,
    "nom": "Jen",
    "prenom": "Smith"
  },
  "conversation": {
    "id": "1084",
    "status": "active"
  },
  "message": {
    "id": "2304",
    "status": "delivered",
    "type": "text",
    "direction": "sent",
    "content": {
      "text": "hello"
    }
  }
}
message.updated event 
{
  "type": "message.updated",
  "contact": {
    "id": "5056",
    "phone": 316123456789,
    "nom": "Jen",
    "prenom": "Smith"
  },
  "conversation": {
    "id": "1084",
    "status": "active"
  },
  "message": {
    "id": "2304",
    "status": "failed",
    "type": "text",
    "direction": "sent",
    "content": {
      "text": "hello"
    }
  }
}

Create Template

L'API Sparrow fournit des points de terminaison pour créer et récupérer des modèles de message.

POST : https://app.sparrowmessage.com/api/v2/whatsapp/templates

Headers :
# Key Value
1 Accept application/json
2 Content-Type application/json
3 Authorization Bearer {api_token}

api_token : récupérable à partir du service d'authentification vérifier ici


Params :
# Paramètre Type Description Requis
1 templateName string Le nom du modèle. Oui
2 hsm_lang string La langue du modèle. Oui
3 category string La catégorie de modèle. Oui
7 text text Contenu de message Oui, sauf pour la catégorie 'AUTHENTICATION'
4 header_type string Type de média Non
5 header string L'URL du média associé. Non
6 buttons_type string Type de média Non

(1) : Type de médias possible sont : text image video document

(2) : Type de Catégorie possible sont : MARKETING UTILITY AUTHENTICATION

(3) : Type de Buttons possible sont : call_to_action : Url,Phone number quick_reply : Maximum 3 buttons

(4) : {{1}} représente le numéro de la variable. Assurez-vous d'envoyer un exemple pour chaque variable dans le template pour valider son fonctionnement correct.

Par exemple, si vous avez une variable {{1}}, vous pouvez la remplir "variable_1" avec une valeur pour illustrer son utilisation.

Exemple : 
{
  "templateName" : "api_template_reply",
  "category" : "MARKETING",
  "hsm_lang" : "fr",
  "text" : "Bonjour {{1}} ce message est un message de la part de {{2}}.",
  "variable_1" : "John",
  "variable_2": "E-solution",
  "buttons_type" : "quick_reply",
  "reply_text_1" : "Intéressé(e)",
  "reply_text_2" : "Pas intéressé(e)"
}
"buttons_type" : call_to_action:
# Type Params
1 url_action string
2 web_site_url url
3 phone_number_action string
4 phone_number number
"buttons_type" : quick_reply:
# Type Params
1 reply_text_1 string
2 reply_text_2 string
3 reply_text_3 string
"category" : AUTHENTICATION:
# Type Params
1 otp_code string
2 otp_expiration int

(1) : : L'ordre des paramètres est important

Response :
{
  "code": "OK/KO",
  "template": "object" // SI code "OK"
  "error" : "string" // Si code "KO"
}

Get Templates

Listez tous vos modèles.

GET : https://app.sparrowmessage.com/api/v2/whatsapp/templates

Headers :
# Key Value
1 Accept application/json
2 Content-Type application/json
3 Authorization Bearer {api_token}

api_token : récupérable à partir du service d'authentification vérifier ici


Response :
{
  "code": "OK/KO",
  "template": "object" // SI code "OK"
  "error" : "string" // Si code "KO"
}

Fetch Templates By Name

Récupérez les détails du modèle avec un nom.

GET : https://app.sparrowmessage.com/api/v2/whatsapp/templates/templateName

Headers :
# Key Value
1 Accept application/json
2 Content-Type application/json
3 Authorization Bearer {api_token}

api_token : récupérable à partir du service d'authentification vérifier ici


Response :
{
  "code": "OK/KO",
  "template": "object" // SI code "OK"
  "error" : "string" // Si code "KO"
}

Delete Template

Supprimer des modèles par nom.

DELETE : https://app.sparrowmessage.com/api/v2/whatsapp/templates/templateName

Headers :
# Key Value
1 Accept application/json
2 Content-Type application/json
3 Authorization Bearer {api_token}

api_token : récupérable à partir du service d'authentification vérifier ici


Response :
{
  "code": "OK/KO",
  "message": "string" // SI code "OK"
  "error" : "string" // Si code "KO"
}