Référence de l’API REST
Cette référence s’adresse aux développeurs qui veulent dialoguer avec l’assistant depuis leur propre code ou réagir aux événements du chat dans WordPress.
L’extension enregistre ses routes dans l’API REST de WordPress sous l’espace de noms ecomai/v1 ; l’URL de base est donc https://yourstore.com/wp-json/ecomai/v1/. Il existe trois routes. Tout le reste de l’administration repose sur des actions AJAX internes à WordPress, qui ne constituent pas une API publique et peuvent changer sans préavis.
Limites de débit
Les messages sont limités par session_id : 20 messages par minute par défaut. Vous modifiez cette valeur avec Limite de débit (messages/minute) sous Paramètres → Comportement → Limites et langue (de 1 à 100). Au-delà de la limite, l’API répond avec le code 429 :
HTTP/1.1 429 Too Many Requests
{ "error": "Rate limit exceeded. Please slow down." }La limite ne s’applique pas pendant qu’un conseiller humain gère la conversation. Le quota de conversations de l’offre Free s’applique aussi aux conversations démarrées par l’API.
Points de terminaison
POST /ecomai/v1/message
Envoie un message client et renvoie la réponse de l’assistant. Le message suit le traitement habituel de l’assistant : votre base de connaissances, les informations produits, les règles d’escalade et l’historique de la conversation pour ce session_id s’appliquent tous. Les parcours de l’éditeur de parcours (Flow Builder) sont pilotés par le widget de chat et ne sont pas démarrés par cette route.
La route ne demande pas d’authentification, puisque des visiteurs anonymes de la boutique utilisent le chat. Protégez-la comme n’importe quel formulaire public, par exemple avec la limitation de débit de votre pare-feu.
Paramètres
message(chaîne, obligatoire) : le texte du client.session_id(chaîne, facultatif) : identifie la conversation. Envoyez la même valeur pour la poursuivre. Si vous l’omettez, un nouvel identifiant est généré et renvoyé.context(objet, facultatif) : des informations sur l’endroit où se trouve le client, commepage_url.
curl -X POST https://yourstore.com/wp-json/ecomai/v1/message \
-H "Content-Type: application/json" \
-d '{"session_id":"abc-123","message":"What is your return policy?"}'Corps de la requête
{
"message": "What is your return policy?",
"session_id": "abc-123",
"context": {
"page_url": "https://yourstore.com/shop/"
}
}Réponse (200)
{
"reply": "You can return any item within 30 days of delivery…",
"session_id": "abc-123",
"chips": ["Start a return", "Track my order"],
"escalated": false
}reply: la réponse de l’assistant.chips: des suggestions de réponses rapides ; la liste peut être vide.escalated:truelorsque la conversation a été transmise à un humain.
POST /ecomai/v1/satisfaction
Enregistre une note en étoiles pour une conversation. Sans authentification.
session_id(chaîne, obligatoire)rating(entier, obligatoire) : de 1 à 5.
{
"session_id": "abc-123",
"rating": 5
}Réponse (200)
{
"success": true,
"message": "Thank you for your feedback!",
"rating": 5
}Une session absente ou une note en dehors de 1 à 5 renvoie le code 400 avec un message error.
GET /ecomai/v1/stream
Une route Server-Sent Events expérimentale qui diffuse la réponse de l’IA au fur et à mesure de sa génération. Les paramètres passent dans la chaîne de requête :
message(chaîne, obligatoire)session_id(chaîne, facultatif)nonce(chaîne, obligatoire) : le nonce de chat à durée de vie courte que l’extension fournit au widget à chaque chargement de page. Sans nonce valide, la route répond 403.
La réponse a le type de contenu text/event-stream. Chaque fragment est un objet JSON, et le flux se termine par [DONE] :
data: {"chunk":"You can return"}
data: {"chunk":" any item within 30 days"}
data: [DONE]Si le fournisseur échoue, le flux envoie un événement error accompagné d’un message. Comme le nonce est lié à une page vue, cette route est destinée au code front-end exécuté sur votre boutique, et non aux appels de serveur à serveur. Pour ceux-ci, utilisez POST /message.
Hooks d’action PHP
Si votre code s’exécute sur le même site WordPress, les hooks sont plus simples que les appels HTTP. L’extension déclenche les actions suivantes :
ecomai_conversation_started($session_id,$context) : une nouvelle conversation a été enregistrée.ecomai_conversation_escalated($session_id,$contact) : un client a envoyé le formulaire d’escalade.ecomai_lead_captured($lead) : une adresse e-mail a été collectée.ecomai_chat_purchase($order_id,$order_data) : une commande a été passée après une conversation.ecomai_satisfaction_rated($session_id,$rating) : un client a noté la conversation.ecomai_discount_offered($session_id,$discount) : l’assistant a proposé un code promo.
add_action( 'ecomai_lead_captured', function ( $lead ) {
// $lead['email'], $lead['name'], $lead['session_id'], $lead['source']
my_crm_add_contact( $lead['email'], $lead['name'] );
} );Un filtre contrôle le widget automatique : ecomai_should_inject_global_widget. Renvoyez false depuis ce filtre pour empêcher l’ajout du widget sur la page en cours.
Shortcode
Utilisez [ecomai_chatbot] pour placer vous-même le chat à la place du widget automatique (ou en complément) :
[ecomai_chatbot]: le widget flottant.[ecomai_chatbot mode="inline"]: un chat intégré au contenu de la page.[ecomai_chatbot type="support"]: le Bot d’assistance dédié à une page d’aide Pro.
Webhooks
Pour recevoir les mêmes événements sur un autre serveur, utilisez les Webhooks Pro. Ce guide décrit la charge utile et la vérification de la signature.
Toujours bloqué ?
Consultez le guide de dépannage, ou contactez le support en nous indiquant ce que vous avez déjà essayé.