Développeurs

Construisez sur MagizAI

Quatre surfaces HTTP, chacune ouverte par son propre jeton. Chaque point de terminaison ci-dessous est lu dans le code qui le sert : les noms de champs de cette page sont exactement ceux que vous recevrez.

URL de base https://magizai.com

Démarrer

Toutes les surfaces parlent JSON en HTTPS et attendent un en-tête Accept: application/json. Envoyez votre jeton dans l'en-tête Authorization, et lisez le code de statut avant le corps : une requête refusée porte toujours un champ message qui l'explique.

JSON uniquement

Les requêtes et les réponses sont en JSON. Seule exception : le point de diffusion du widget, qui renvoie des Server-Sent Events.

Limité à l'espace de travail

Un jeton n'atteint jamais que l'espace de travail où il a été créé. Demander un chatbot ou une conversation appartenant à un autre compte renvoie 404, jamais les données d'un autre espace.

Sans état

Ni cookie, ni jeton CSRF, ni session. Chaque requête porte ses propres identifiants : le même appel fonctionne depuis un serveur, une application mobile ou une tâche planifiée.

curl https://magizai.com/api/v1/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Authentification

Les jetons sont des jetons Bearer de Laravel Sanctum. Chacun porte un droit qui décide de la surface qu'il ouvre, et ce droit est vérifié à chaque requête.

Authorization: Bearer <token>
Accept: application/json

Jeton REST API

Créé dans le tableau de bord, sous Paramètres, dans le panneau Rest API tokens. Nommez-le, copiez sa valeur une seule fois (elle n'est montrée qu'à ce moment) et utilisez-le sur les points v1. Un compte peut détenir jusqu'à vingt jetons, et une révocation prend effet immédiatement.

ability: api

Jeton de portail

Émis en envoyant un e-mail et un mot de passe du tableau de bord au point de connexion du portail. Seul un propriétaire ou un administrateur d'un espace où le portail en marque blanche est activé peut en obtenir un.

ability: portal

Jeton d'agent

Émis en envoyant un e-mail et un mot de passe au point de connexion des agents. Propriétaires, administrateurs et agents peuvent se connecter ; un siège lecteur en lecture seule est refusé. Les applications renouvellent le jeton avant son expiration.

ability: agent

Points du widget

Aucun jeton. La clé publique du chatbot figure dans l'URL, et un visiteur prouve qu'une conversation est la sienne en envoyant le même identifiant de visiteur que celui qui l'a ouverte.

Les types de jetons ne sont pas interchangeables. Un jeton créé dans les Paramètres n'ouvre que les points v1 : envoyé sur une route portal ou agent, il renvoie 403, car ces routes exigent les droits portal et agent qu'un jeton de Paramètres ne porte pas. Les jetons de portail et d'agent viennent de leurs propres points de connexion.

Tout jeton expire trente jours après son émission. Les applications agents renouvellent le leur via le point refresh ; pour une intégration serveur, créez un remplaçant avant l'expiration de l'ancien.

Erreurs

Une requête en échec renvoie le statut HTTP correspondant et un corps JSON. Les échecs de validation suivent la forme Laravel : un message lisible et un objet errors indexé par nom de champ.

{
  "message": "The message field is required.",
  "errors": {
    "message": ["The message field is required."]
  }
}

Statut	Ce qui le déclenche
401	Le jeton est absent, mal formé, expiré ou révoqué.
403	Le jeton est valide mais pas autorisé ici : mauvais droit pour cette surface, rôle sans la permission, ou compte ou espace de travail suspendu.
404	L'enregistrement n'existe pas, ou il appartient à un autre espace de travail. Les deux cas sont volontairement indiscernables.
409	La requête entre en conflit avec l'état actuel, par exemple inviter un visiteur qui a déjà quitté le site.
422	La validation a échoué, ou une règle métier a refusé la requête. Lisez l'objet errors pour savoir quel champ et pourquoi.
429	Une limite de débit ou un verrouillage de compte a été atteint. Attendez le nombre de secondes indiqué par l'en-tête Retry-After.
500	Une erreur est survenue de notre côté. L'action n'a pas abouti.
502	Le fournisseur d'IA est injoignable. Vérifiez la clé configurée pour l'espace de travail.
503	Une capacité n'est pas configurée sur ce serveur, par exemple les notifications web sans clés VAPID.

Limites de débit

Les limites sont définies par route et chaque point ci-dessous indique la sienne. Sur les routes authentifiées le compte se fait par utilisateur connecté ; sur les routes publiques, par adresse IP.

Une réponse limitée porte les en-têtes habituels : le refus vous dit exactement combien de temps attendre.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
Retry-After: 41

Les points marqués « Aucune limite de route » n'ont pas de limite propre. Ils restent soumis au quota mensuel de messages de votre formule : interrogez-les à intervalle raisonnable plutôt qu'en boucle serrée.

REST API (v1)

L'API d'intégration généraliste. Lisez vos chatbots et vos conversations, ajoutez des connaissances, et envoyez un message visiteur pour recevoir la réponse de l'IA dans une seule réponse JSON. Authentifiée par un jeton créé dans les Paramètres.

Chemin de base /api/v1 · 7 points de terminaison

GET /api/v1/me

Renvoie l'utilisateur à qui appartient le jeton, et son espace de travail.

Authentification Jeton Bearer (api) Limite de débit Aucune limite de route

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/v1/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "user": {
    "id": 12,
    "name": "Amelia Fox",
    "email": "[email protected]",
    "role": "owner"
  },
  "company": {
    "id": 3,
    "name": "Acme Ltd",
    "slug": "acme-ltd",
    "plan": "pro"
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

GET /api/v1/chatbots

Liste tous les chatbots de l'espace de travail.

Authentification Jeton Bearer (api) Limite de débit Aucune limite de route

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/v1/chatbots \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "data": [
    {
      "id": 7,
      "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
      "name": "Support bot",
      "provider": "claude",
      "model": "claude-haiku-4-5",
      "is_active": true
    }
  ]
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

GET /api/v1/chatbots/{key}

Renvoie un chatbot, avec l'apparence de son widget et le nombre de sources de connaissances qu'il contient.

Authentification Jeton Bearer (api) Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.

Requête

curl https://magizai.com/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "data": {
    "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
    "name": "Support bot",
    "provider": "claude",
    "model": "claude-haiku-4-5",
    "is_active": true,
    "knowledge_sources": 14,
    "branding": {
      "primary_color": "#4f46e5",
      "launcher_text": "Chat with us",
      "position": "right",
      "theme": "minimal",
      "logo_url": null,
      "avatar_url": null,
      "title": "Support bot",
      "subtitle": "We typically reply in a few seconds",
      "layout": "classic",
      "launcher": "bubble",
      "quick_replies": [],
      "agent_avatars": [],
      "composer_style": "full",
      "sound": true,
      "screen_share": false,
      "copilot": false,
      "auto_actions": true,
      "copilot_use_profile": false,
      "copilot_autostart": true,
      "live_visitors": true,
      "behavior_tracking": false,
      "recommend_mode": "reactive",
      "proactive": {
        "enabled": false,
        "message": "Hi! Anything I can help you find?",
        "delay": 20,
        "scroll": 0,
        "exit_intent": false,
        "url_contains": "",
        "frequency": "session"
      }
    }
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	Aucun enregistrement de ce type dans cet espace de travail.

GET /api/v1/chatbots/{key}/conversations

Liste les conversations d'un chatbot, activité la plus récente en tête, sous forme paginée.

Authentification Jeton Bearer (api) Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
per_page	integer	Facultatif	Requête. Lignes par page. Par défaut 20, plafonné à 100.

Requête

curl "https://magizai.com/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations?per_page=2" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "current_page": 1,
  "data": [
    {
      "id": 4821,
      "public_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
      "status": "bot",
      "visitor_id": "v_2c9a71b4e5",
      "last_message_at": "2026-08-08T09:41:12.000000Z"
    },
    {
      "id": 4820,
      "public_id": "1d3f92ac-77b1-4a0d-8c6e-2f5a9b4c1d70",
      "status": "closed",
      "visitor_id": "v_71ad03f9c2",
      "last_message_at": "2026-08-08T08:02:55.000000Z"
    }
  ],
  "first_page_url": "https://magizai.com/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations?page=1",
  "from": 1,
  "last_page": 34,
  "last_page_url": "https://magizai.com/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations?page=34",
  "next_page_url": "https://magizai.com/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations?page=2",
  "path": "https://magizai.com/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations",
  "per_page": 2,
  "prev_page_url": null,
  "to": 2,
  "total": 67
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	Aucun enregistrement de ce type dans cet espace de travail.

POST /api/v1/chatbots/{key}/knowledge

Ajoute un document texte ou une paire question-réponse à un chatbot et l'entraîne immédiatement.

Authentification Jeton Bearer (api) Droit du rôle manage-content Limite de débit Aucune limite de route

L'entraînement se fait dans la requête et non dans une file, donc l'appel reste bloqué jusqu'à l'indexation du document. Comptez plusieurs secondes pour un document long.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
title	string	Obligatoire	Un nom pour le document. Jusqu'à 200 caractères.
content	string	Obligatoire	Le texte du document.
type	string	Facultatif	text ou qa. Par défaut text.

Requête

curl -X POST https://magizai.com/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "title": "Refund policy",
        "type": "text",
        "content": "We refund any order within 30 days of delivery. Ship it back with the original packing slip and we credit the original payment method within five working days."
      }'

Réponse

{
  "data": {
    "id": 918,
    "title": "Refund policy",
    "type": "text",
    "status": "ready",
    "chunk_count": 3
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Un champ a échoué à la validation. L'objet errors le nomme.
422	Le document a été enregistré mais n'a pas pu être entraîné. La réponse porte son identifiant et son statut pour relancer l'entraînement sans le renvoyer.

POST /api/v1/chatbots/{key}/messages

Envoie un message visiteur et renvoie la réponse de l'IA en une seule réponse, sans diffusion.

Authentification Jeton Bearer (api) Droit du rôle handle-conversations Limite de débit Aucune limite de route

La réponse est générée entièrement avant l'envoi. Pour recevoir les jetons au fil de l'eau, utilisez plutôt le point de diffusion du widget. Quand un humain a repris la conversation, reply vaut null et note en explique la raison.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
message	string	Obligatoire	Le message du visiteur. Jusqu'à 4000 caractères, et il ne peut pas être uniquement des espaces.
visitor_id	string	Obligatoire	L'identifiant que votre widget attribue à un visiteur et conserve pour la session. Jusqu'à 100 caractères.
conversation_id	uuid	Facultatif	Une conversation existante à poursuivre. Omettez-le pour en démarrer une nouvelle.
meta	object	Facultatif	Contexte libre enregistré sur la conversation.

Requête

curl -X POST https://magizai.com/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "message": "How long does delivery to Dubai take?"
      }'

Réponse

{
  "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
  "status": "bot",
  "reply": {
    "id": 33127,
    "content": "Orders to Dubai arrive in two to four working days with DHL Express. You get a tracking link by email as soon as the parcel leaves our warehouse.",
    "model": "claude-haiku-4-5",
    "tokens_in": 812,
    "tokens_out": 41
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	L'espace de travail a atteint sa limite mensuelle de messages.
502	Le fournisseur d'IA est injoignable. Vérifiez la clé configurée pour l'espace de travail.

GET /api/v1/conversations/{conversation}

Renvoie une conversation avec sa transcription complète.

Authentification Jeton Bearer (api) Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.

Requête

curl https://magizai.com/api/v1/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "data": {
    "id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
    "status": "bot",
    "visitor_id": "v_2c9a71b4e5",
    "messages": [
      {
        "id": 33126,
        "role": "visitor",
        "content": "How long does delivery to Dubai take?",
        "created_at": "2026-08-08T09:41:04.000000Z"
      },
      {
        "id": 33127,
        "role": "assistant",
        "content": "Orders to Dubai arrive in two to four working days with DHL Express.",
        "created_at": "2026-08-08T09:41:07.000000Z"
      }
    ]
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	Aucun enregistrement de ce type dans cet espace de travail.

API du portail

L'API locataire derrière le portail en marque blanche qu'un client peut héberger sur son propre domaine. Elle gère les chatbots, les connaissances, les clés de fournisseurs, l'usage et le code d'intégration. Les données et l'IA restent sur la plateforme, et une clé de fournisseur enregistrée n'est jamais renvoyée au navigateur.

Chemin de base /api/portal · 14 points de terminaison

POST /api/portal/login

Échange un e-mail et un mot de passe du tableau de bord contre un jeton Bearer de portail.

Authentification Aucune, public Limite de débit 10 requêtes toutes les 1 min, par adresse IP

Les échecs sont volontairement vagues : mot de passe erroné, adresse inconnue, portail désactivé et rôle insuffisant renvoient tous le même texte, si bien que le point ne permet pas de découvrir quels comptes existent. Les tentatives partagent un compteur de verrouillage avec le formulaire de connexion web.

Paramètres

Paramètre	Type	Obligatoire	Description
email	string	Obligatoire	L'adresse e-mail d'un utilisateur du tableau de bord. Jusqu'à 255 caractères.
password	string	Obligatoire	Le mot de passe de cet utilisateur.

Requête

curl -X POST https://magizai.com/api/portal/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "email": "[email protected]",
        "password": "correct-horse-battery-staple"
      }'

Réponse

{
  "token": "17|Ck2Ft9pQvYb3xLmR8sJd0aWnZeH6uT4gPqK1oI5c",
  "user": {
    "name": "Amelia Fox",
    "email": "[email protected]",
    "role": "owner"
  },
  "company": {
    "name": "Acme Ltd",
    "plan": "pro"
  },
  "brand": {
    "name": "Acme Support",
    "powered_by": "MagizAI",
    "logo_url": "https://cdn.acme.test/logo.svg"
  }
}

Erreurs

Statut	Ce qui le déclenche
401	L'e-mail ou le mot de passe est erroné. Le texte est le même que l'adresse existe ou non.
403	Le portail est désactivé pour cet espace, l'espace est suspendu, ou l'utilisateur n'est ni propriétaire ni administrateur. Formulé exactement comme un mot de passe erroné, volontairement.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	Trop de tentatives, via la limite de route ou le verrouillage de compte partagé. L'en-tête Retry-After indique le délai.

POST /api/portal/logout

Révoque le jeton de portail utilisé pour l'appel.

Authentification Jeton Bearer (portal) Limite de débit Aucune limite de route

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl -X POST https://magizai.com/api/portal/logout \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "message": "Signed out."
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

GET /api/portal/me

Renvoie l'utilisateur connecté, l'espace de travail, sa marque blanche, les limites de la formule et l'usage du mois.

Authentification Jeton Bearer (portal) Limite de débit Aucune limite de route

monthly_message_limit vaut null sur une formule illimitée, et usage_percent vaut null avec lui.

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/portal/me \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "user": {
    "name": "Amelia Fox",
    "email": "[email protected]",
    "role": "owner"
  },
  "company": {
    "name": "Acme Ltd",
    "plan": "pro"
  },
  "brand": {
    "name": "Acme Support",
    "powered_by": "MagizAI",
    "logo_url": "https://cdn.acme.test/logo.svg"
  },
  "limits": {
    "plan": "Pro",
    "monthly_message_limit": 10000,
    "chatbot_limit": 5,
    "agent_seats": 10
  },
  "usage": {
    "messages_used": 3142,
    "message_limit": 10000,
    "usage_percent": 31,
    "chatbots": 2
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

GET /api/portal/chatbots

Liste tous les chatbots de l'espace avec leur nombre de sources et de conversations.

Authentification Jeton Bearer (portal) Limite de débit Aucune limite de route

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/portal/chatbots \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "data": [
    {
      "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
      "name": "Support bot",
      "role": "support",
      "provider": "claude",
      "model": "claude-haiku-4-5",
      "is_active": true,
      "knowledge_sources": 14,
      "conversations": 67
    }
  ]
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

GET /api/portal/chatbots/{key}

Renvoie un chatbot avec sa persona, ses instructions, son message d'accueil et son apparence.

Authentification Jeton Bearer (portal) Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.

Requête

curl https://magizai.com/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "data": {
    "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
    "name": "Support bot",
    "role": "support",
    "provider": "claude",
    "model": "claude-haiku-4-5",
    "is_active": true,
    "knowledge_sources": 14,
    "conversations": 67,
    "persona": "Warm, direct, never oversells.",
    "instructions": "Always quote delivery times from the shipping table.",
    "welcome_message": "Hi! How can I help you today?",
    "branding": {
      "primary_color": "#4f46e5",
      "launcher_text": "Chat with us",
      "position": "right",
      "theme": "minimal",
      "logo_url": null,
      "avatar_url": null,
      "title": "Support bot",
      "subtitle": "We typically reply in a few seconds",
      "layout": "classic",
      "launcher": "bubble",
      "quick_replies": [],
      "agent_avatars": [],
      "composer_style": "full",
      "sound": true,
      "screen_share": false,
      "copilot": false,
      "auto_actions": true,
      "copilot_use_profile": false,
      "copilot_autostart": true,
      "live_visitors": true,
      "behavior_tracking": false,
      "recommend_mode": "reactive",
      "proactive": {
        "enabled": false,
        "message": "Hi! Anything I can help you find?",
        "delay": 20,
        "scroll": 0,
        "exit_intent": false,
        "url_contains": "",
        "frequency": "session"
      }
    }
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	Aucun enregistrement de ce type dans cet espace de travail.

PUT /api/portal/chatbots/{key}

Met à jour le contenu d'un chatbot et l'apparence du widget.

Authentification Jeton Bearer (portal) Droit du rôle manage-chatbots Limite de débit Aucune limite de route

name est obligatoire à chaque appel. Les champs d'apparence sont fusionnés avec l'existant : n'envoyer que primary_color laisse le reste intact, et un welcome_message vide le remet au message d'accueil par défaut. Le fournisseur et le modèle d'IA ne se changent pas ici.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
name	string	Obligatoire	Le nom du chatbot. Jusqu'à 120 caractères.
persona	string	Facultatif	Le ton que doit adopter l'assistant. Jusqu'à 2000 caractères.
instructions	string	Facultatif	Instructions permanentes pour l'assistant. Jusqu'à 4000 caractères.
welcome_message	string	Facultatif	Le message affiché à l'ouverture du chat. Jusqu'à 300 caractères ; vide, il revient au message par défaut.
is_active	boolean	Facultatif	Si le chatbot répond. Omettez-le pour conserver le réglage actuel.
primary_color	string	Facultatif	Couleur d'accent du widget, en hexadécimal. Jusqu'à 9 caractères.
launcher_text	string	Facultatif	Libellé du bouton d'ouverture du chat. Jusqu'à 40 caractères.
position	string	Facultatif	Le côté où se place le widget : left ou right.
theme	string	Facultatif	Thème du widget : minimal, ocean, emerald, midnight, sunset, crisp, violet, rose, slate ou forest.

Requête

curl -X PUT https://magizai.com/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "Support bot",
        "welcome_message": "Hi! Ask me anything about your order.",
        "primary_color": "#0a7d5f",
        "position": "right",
        "theme": "emerald",
        "is_active": true
      }'

Réponse

{
  "data": {
    "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
    "name": "Support bot",
    "role": "support",
    "provider": "claude",
    "model": "claude-haiku-4-5",
    "is_active": true,
    "knowledge_sources": 14,
    "conversations": 67,
    "persona": "Warm, direct, never oversells.",
    "instructions": "Always quote delivery times from the shipping table.",
    "welcome_message": "Hi! Ask me anything about your order.",
    "branding": {
      "primary_color": "#0a7d5f",
      "launcher_text": "Chat with us",
      "position": "right",
      "theme": "emerald"
    }
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Un champ a échoué à la validation. L'objet errors le nomme.

GET /api/portal/chatbots/{key}/knowledge

Liste les sources de connaissances d'un chatbot et leur état d'entraînement.

Authentification Jeton Bearer (portal) Limite de débit Aucune limite de route

Seules les sources de premier niveau sont listées. Les pages découvertes lors de l'exploration d'une URL sont rattachées à cette source et n'apparaissent pas séparément.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.

Requête

curl https://magizai.com/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "data": [
    {
      "id": 918,
      "type": "text",
      "title": "Refund policy",
      "source_url": null,
      "status": "ready",
      "chunk_count": 3,
      "created_at": "2026-08-08T09:12:44+00:00"
    },
    {
      "id": 902,
      "type": "url",
      "title": "acme.test",
      "source_url": "https://acme.test/shipping",
      "status": "processing",
      "chunk_count": 0,
      "created_at": "2026-08-07T16:30:02+00:00"
    }
  ]
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	Aucun enregistrement de ce type dans cet espace de travail.

POST /api/portal/chatbots/{key}/knowledge

Ajoute une note texte, une paire question-réponse, ou une URL à explorer.

Authentification Jeton Bearer (portal) Droit du rôle manage-content Limite de débit Aucune limite de route

Les champs obligatoires dépendent de type : content pour text, question et answer pour qa, source_url pour url. La source est créée aussitôt avec le statut pending puis indexée en arrière-plan : interrogez le point de liste pour la voir passer à ready.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
type	string	Obligatoire	text, qa ou url. C'est lui qui décide des champs obligatoires ci-dessous.
title	string	Facultatif	Un nom pour la source. Omis, il retombe sur une valeur adaptée au type.
content	string	Facultatif	Obligatoire quand type vaut text. Le corps de la note, jusqu'à 1 000 000 de caractères.
question	string	Facultatif	Obligatoire quand type vaut qa. Jusqu'à 2000 caractères.
answer	string	Facultatif	Obligatoire quand type vaut qa. Jusqu'à 50 000 caractères.
source_url	url	Facultatif	Obligatoire quand type vaut url. La page à explorer, jusqu'à 2048 caractères.

Requête

curl -X POST https://magizai.com/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "type": "qa",
        "title": "Weekend delivery",
        "question": "Do you deliver on Saturdays?",
        "answer": "Yes. Saturday delivery is available in Dubai and Abu Dhabi at no extra cost."
      }'

Réponse

{
  "data": {
    "id": 919,
    "type": "qa",
    "title": "Weekend delivery",
    "source_url": null,
    "status": "pending",
    "chunk_count": 0,
    "created_at": "2026-08-08T10:04:18+00:00"
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Un champ a échoué à la validation. L'objet errors le nomme.

DELETE /api/portal/chatbots/{key}/knowledge/{source}

Supprime une source de connaissances, son fichier stocké et tout ce qui en a été indexé.

Authentification Jeton Bearer (portal) Droit du rôle manage-content Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
source	integer	Obligatoire	Chemin. L'identifiant de la source de connaissances.

Requête

curl -X DELETE https://magizai.com/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge/919 \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "message": "Knowledge source removed."
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.

GET /api/portal/keys

Liste tous les fournisseurs d'IA et indique si cet espace possède sa propre clé.

Authentification Jeton Bearer (portal) Limite de débit Aucune limite de route

Une clé enregistrée n'est jamais renvoyée, seulement ses quatre derniers caractères et le fait qu'elle existe.

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/portal/keys \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "data": [
    { "provider": "claude",     "label": "Anthropic Claude", "last_four": "9f2c", "configured": true },
    { "provider": "openai",     "label": "OpenAI",           "last_four": null,   "configured": false },
    { "provider": "gemini",     "label": "Google Gemini",    "last_four": null,   "configured": false },
    { "provider": "deepseek",   "label": "DeepSeek",         "last_four": null,   "configured": false },
    { "provider": "kimi",       "label": "Moonshot Kimi",    "last_four": null,   "configured": false },
    { "provider": "groq",       "label": "Groq (Llama)",     "last_four": null,   "configured": false },
    { "provider": "mistral",    "label": "Mistral",          "last_four": null,   "configured": false },
    { "provider": "openrouter", "label": "OpenRouter",       "last_four": null,   "configured": false }
  ]
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

PUT /api/portal/keys/{provider}

Enregistre ou remplace la clé de l'espace pour un fournisseur d'IA.

Authentification Jeton Bearer (portal) Droit du rôle manage-workspace Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
provider	string	Obligatoire	Chemin. Code du fournisseur : claude, openai, gemini, deepseek, kimi, groq, mistral ou openrouter.
api_key	string	Obligatoire	La clé d'API du fournisseur. Stockée chiffrée et jamais renvoyée. Jusqu'à 300 caractères.

Requête

curl -X PUT https://magizai.com/api/portal/keys/openai \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "api_key": "sk-proj-0f4c8b2e6a1d7f3c9b5e0a2d" }'

Réponse

{
  "data": {
    "provider": "openai",
    "last_four": "a2d0",
    "configured": true
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
422	Ce code de fournisseur n'est pas reconnu.
422	Un champ a échoué à la validation. L'objet errors le nomme.

DELETE /api/portal/keys/{provider}

Supprime la clé de l'espace pour un fournisseur d'IA.

Authentification Jeton Bearer (portal) Droit du rôle manage-workspace Limite de débit Aucune limite de route

Idempotent. Supprimer un fournisseur sans clé renvoie quand même 200, avec un message indiquant qu'aucune clé n'était enregistrée.

Paramètres

Paramètre	Type	Obligatoire	Description
provider	string	Obligatoire	Chemin. Code du fournisseur : claude, openai, gemini, deepseek, kimi, groq, mistral ou openrouter.

Requête

curl -X DELETE https://magizai.com/api/portal/keys/openai \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "message": "API key removed."
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
422	Ce code de fournisseur n'est pas reconnu.

GET /api/portal/analytics

Renvoie les totaux du mois pour les conversations, messages, jetons et coûts de l'espace.

Authentification Jeton Bearer (portal) Limite de débit Aucune limite de route

cost est en unités entières de devise, converti depuis les totaux en micro-centimes conservés en interne. La période commence toujours le premier jour du mois en cours.

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/portal/analytics \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "data": {
    "period": "month",
    "since": "2026-08-01T00:00:00+00:00",
    "conversations": 412,
    "messages": {
      "ai_replies": 1904,
      "human_replies": 233,
      "visitor_messages": 2088,
      "total": 4225
    },
    "tokens": 1874320,
    "cost": 4.216874,
    "messages_used": 3142
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

GET /api/portal/widget-snippet

Renvoie la balise script d'intégration prête à coller pour le chatbot de l'espace.

Authentification Jeton Bearer (portal) Limite de débit Aucune limite de route

Prend le premier chatbot actif, à défaut le plus récemment créé.

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/portal/widget-snippet \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "data": {
    "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
    "snippet": "<script src=\"https://magizai.com/widget.js\" data-key=\"cv_9f2a4c7e1b6d3a8f5c0e2b4d\" defer></script>"
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	L'espace n'a pas encore de chatbot, il n'y a donc aucun code à renvoyer.

API des applications agents

L'API derrière les applications agents mobiles et bureau. Elle fait tourner la boîte de réception : lire les conversations, répondre, reprendre la main, résoudre, étiqueter, utiliser l'assistant IA, suivre les visiteurs en direct et enregistrer un appareil pour les notifications. Chaque action exécute la même logique locataire que la boîte web, donc le comportement est identique.

Chemin de base /api/agent · 32 points de terminaison

POST /api/agent/login

Échange un e-mail et un mot de passe contre un jeton Bearer d'agent.

Authentification Aucune, public Limite de débit 10 requêtes toutes les 1 min, par adresse IP

Seuls les propriétaires, administrateurs et agents peuvent se connecter ici. Un siège lecteur est refusé, tout comme un compte dont l'espace est suspendu. Les tentatives partagent un compteur de verrouillage avec le formulaire de connexion web et l'API du portail.

Paramètres

Paramètre	Type	Obligatoire	Description
email	string	Obligatoire	L'adresse e-mail d'un utilisateur du tableau de bord. Jusqu'à 255 caractères.
password	string	Obligatoire	Le mot de passe de cet utilisateur.
device_name	string	Facultatif	Un libellé pour cet appareil, affiché à côté du jeton. Jusqu'à 120 caractères.

Requête

curl -X POST https://magizai.com/api/agent/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "email": "[email protected]",
        "password": "correct-horse-battery-staple",
        "device_name": "Sara iPhone 15"
      }'

Réponse

{
  "token": "42|Yb7Kd1sQvNc3xLmR8sJd0aWnZeH6uT4gPqK1oI5c",
  "expires_at": "2026-09-07T10:14:02+00:00",
  "device_name": "Sara iPhone 15",
  "user": {
    "id": 58,
    "name": "Sara Bell",
    "email": "[email protected]",
    "role": "Agent",
    "avatar": "https://cdn.acme.test/avatars/58.png"
  },
  "company": {
    "id": 3,
    "name": "Acme Ltd",
    "plan": "pro"
  }
}

Erreurs

Statut	Ce qui le déclenche
401	L'e-mail ou le mot de passe est erroné. Le texte est le même que l'adresse existe ou non.
403	Ce compte ne peut pas traiter de conversations, ou son espace de travail est indisponible.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	Trop de tentatives, via la limite de route ou le verrouillage de compte partagé. L'en-tête Retry-After indique le délai.

POST /api/agent/refresh

Échange un jeton d'agent encore valide contre un jeton neuf.

Authentification Jeton Bearer (agent) Limite de débit 6 requêtes toutes les 60 min, par utilisateur connecté

Renouvelez une fois le jeton passé la moitié de sa vie. L'ancien jeton est laissé expirer de lui-même plutôt que révoqué, pour qu'une réponse perdue en route ne déconnecte jamais un appareil.

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl -X POST https://magizai.com/api/agent/refresh \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "token": "43|Qw9Lm2tRvNc3xLmR8sJd0aWnZeH6uT4gPqK1oI5c",
  "expires_at": "2026-09-07T11:02:31+00:00",
  "device_name": "Sara iPhone 15",
  "user": {
    "id": 58,
    "name": "Sara Bell",
    "email": "[email protected]",
    "role": "Agent",
    "avatar": "https://cdn.acme.test/avatars/58.png"
  },
  "company": {
    "id": 3,
    "name": "Acme Ltd",
    "plan": "pro"
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
429	La limite de route pour cet utilisateur a été atteinte.

GET /api/agent/me

Renvoie l'agent connecté, son espace de travail, et la date d'expiration du jeton en cours.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/agent/me \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "user": {
    "id": 58,
    "name": "Sara Bell",
    "email": "[email protected]",
    "role": "Agent",
    "avatar": "https://cdn.acme.test/avatars/58.png"
  },
  "company": {
    "id": 3,
    "name": "Acme Ltd",
    "plan": "pro"
  },
  "expires_at": "2026-09-07T10:14:02+00:00",
  "device_name": "Sara iPhone 15"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

POST /api/agent/logout

Révoque le jeton d'agent utilisé pour l'appel.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl -X POST https://magizai.com/api/agent/logout \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "message": "Signed out."
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

POST /api/agent/broadcasting/auth

Autorise l'abonnement à un canal temps réel pour une application qui porte un jeton au lieu d'un cookie de session.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Le point de diffusion natif de Laravel attend un cookie de session, que les applications n'ont pas. C'est la même logique d'autorisation, atteinte avec un jeton Bearer.

Paramètres

Paramètre	Type	Obligatoire	Description
socket_id	string	Obligatoire	L'identifiant de socket fourni par la connexion temps réel.
channel_name	string	Obligatoire	Le canal auquel l'abonnement est demandé.

Requête

curl -X POST https://magizai.com/api/agent/broadcasting/auth \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "socket_id": "812734.1904221",
        "channel_name": "private-company.3"
      }'

Réponse

{
  "auth": "reverbappkey:6f1c0a9b8e7d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
403	Le porteur du jeton n'est pas autorisé sur ce canal.

GET /api/agent/inbox

Renvoie le flux de la boîte de réception : liste des conversations, compteurs de non-lus et totaux par section.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Une réponse porte au plus 60 lignes, alors que groups compte toute la boîte : utilisez filter pour atteindre le reste d'une section. Passer conversation renvoie ce fil dans active et le marque comme lu.

Paramètres

Paramètre	Type	Obligatoire	Description
filter	string	Facultatif	Requête. Restreint la liste : all, waiting, mine, team, ai, human ou resolved. Par défaut all.
conversation	uuid	Facultatif	Requête. Ouvre cette conversation, la renvoie dans active et la marque comme lue.

Requête

curl "https://magizai.com/api/agent/inbox?filter=waiting" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "conversations": [
    {
      "id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
      "chatbot": "Support bot",
      "visitor": "Nadia Karim",
      "email": "[email protected]",
      "status": "agent",
      "channel": "website",
      "last_at": "2 minutes ago",
      "preview": "I still have not received the replacement…",
      "escalated": true,
      "unread": 2,
      "resolution": null,
      "tags": [
        { "id": 4, "name": "Delivery", "color": "#0a7d5f" }
      ],
      "group": "waiting",
      "handoff_state": "handoff_pending",
      "assigned_to": null,
      "mine": false,
      "online": true,
      "waiting_seconds": 143
    }
  ],
  "counts": {
    "all": 412,
    "ai": 301,
    "human": 74,
    "resolved": 37,
    "unread": 6
  },
  "groups": {
    "waiting": 3,
    "mine": 5,
    "team": 12,
    "ai": 355,
    "resolved": 37
  },
  "listed": 1,
  "list_limit": 60,
  "active": null
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

GET /api/agent/conversations/{conversation}

Renvoie une conversation complète, avec sa transcription, le profil du visiteur, les étiquettes, les notes et les événements.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

C'est le point de la boîte de réception avec la conversation présélectionnée : le corps a la même forme et le fil demandé arrive dans active. Un identifiant absent de cet espace n'est pas une erreur : vous recevez quand même 200, avec active à null. Ouvrir une conversation la marque comme lue.

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.

Requête

curl https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "conversations": [],
  "counts": { "all": 412, "ai": 301, "human": 74, "resolved": 37, "unread": 6 },
  "groups": { "waiting": 3, "mine": 5, "team": 12, "ai": 355, "resolved": 37 },
  "listed": 0,
  "list_limit": 60,
  "active": {
    "id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
    "status": "agent",
    "resolution": null,
    "resolved_at": null,
    "handoff_requested_at": "Aug 8, 2026 · 10:41 AM",
    "escalated": true,
    "resolved_by_ai": false,
    "events": [
      { "type": "human_connected", "source": "agent", "at": "Aug 8 · 10:42 AM" }
    ],
    "tags": [
      { "id": 4, "name": "Delivery", "color": "#0a7d5f", "source": "manual" }
    ],
    "tag_suggestions": [
      { "id": 71, "name": "Refund", "confidence": 0.82, "reason": "Visitor asked for money back." }
    ],
    "visitor": "Nadia Karim",
    "chatbot": "Support bot",
    "channel": "website",
    "email": "[email protected]",
    "phone": null,
    "page": "https://acme.test/orders/8812",
    "locale": "en",
    "joined": "Aug 8, 2026",
    "msg_count": 9,
    "group": "mine",
    "handoff_state": "human_connected",
    "assigned_to": "Sara Bell",
    "mine": true,
    "online": true,
    "last_seen": "12 seconds ago",
    "waiting_seconds": null,
    "referrer": "https://www.google.com/",
    "entry_page": "https://acme.test/",
    "device": "mobile",
    "browser": "Safari",
    "os": "iOS",
    "country": "AE",
    "timezone": "Asia/Dubai",
    "page_views": 6,
    "prechat": [
      { "field": "name", "value": "Nadia Karim" },
      { "field": "email", "value": "[email protected]" }
    ],
    "prechat_greeting": "Before we start, please introduce yourself.",
    "journey": [
      { "url": "https://acme.test/orders/8812", "at": "Aug 8 · 10:38 AM" },
      { "url": "https://acme.test/", "at": null }
    ],
    "revenue_cents": 24900,
    "revenue_amount": 249.0,
    "revenue_currency": "AED",
    "revenue_label": "AED 249.00",
    "summary": "Replacement for order 8812 never arrived; courier shows delivered.",
    "summary_at": "3 minutes ago",
    "intent": "support",
    "lead_id": 233,
    "lead_status": "new",
    "messages": [
      { "id": 33126, "role": "visitor", "content": "I still have not received the replacement.", "at": "10:41 AM" },
      { "id": 33127, "role": "agent", "content": "Let me pull up the courier record now.", "at": "10:42 AM" }
    ],
    "notes": [
      { "id": 12, "body": "Courier claims delivered — opening a claim.", "author": "Sara Bell", "at": "Aug 8 · 10:44 AM" }
    ],
    "watchers": [],
    "watching": false,
    "detected_language": "en",
    "routed_by": "VIP customers",
    "blocked": false,
    "abuse_strikes": 0
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

POST /api/agent/conversations/{conversation}/reply

Envoie une réponse d'agent et la délivre sur le canal utilisé par la conversation.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit Aucune limite de route

Envoyer une réponse reprend automatiquement la conversation. Passez client_id depuis une file d'envoi hors ligne pour sécuriser les reprises : un renvoi avec le même identifiant retourne le message déjà créé et met duplicate à true au lieu d'en envoyer un second.

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.
body	string	Obligatoire	La réponse à envoyer. Jusqu'à 4000 caractères, et elle ne peut pas être uniquement des espaces.
client_id	string	Facultatif	Votre propre identifiant pour cette réponse. Le renvoyer retourne le message déjà créé au lieu d'un second. Jusqu'à 64 caractères.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/reply \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "body": "I have opened a claim with the courier and posted a replacement today.",
        "client_id": "outbox-2026-08-08-0007"
      }'

Réponse

{
  "message": {
    "id": 33131,
    "role": "agent",
    "content": "I have opened a claim with the courier and posted a replacement today.",
    "at": "10:47 AM"
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	La réponse ne contenait que des espaces.
422	Un champ a échoué à la validation. L'objet errors le nomme.

POST /api/agent/conversations/{conversation}/takeover

Reprend la conversation à l'IA et l'attribue à l'agent appelant.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/takeover \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "status": "agent"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.

POST /api/agent/conversations/{conversation}/release

Rend la conversation à l'IA.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/release \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "status": "bot"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.

POST /api/agent/conversations/{conversation}/resolve

Clôt la conversation comme résolue.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit Aucune limite de route

Une conversation résolue se rouvre d'elle-même si le visiteur revient avec un nouveau message.

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/resolve \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "status": "closed",
  "resolution": "resolved"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.

POST /api/agent/conversations/{conversation}/reopen

Rouvre une conversation close et la rend à l'IA.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/reopen \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "status": "bot"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.

GET /api/agent/tags

Liste le catalogue d'étiquettes de l'espace de travail.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/agent/tags \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "tags": [
    { "id": 4, "name": "Delivery", "color": "#0a7d5f" },
    { "id": 5, "name": "Refund", "color": "#b4531f" }
  ]
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

POST /api/agent/conversations/{conversation}/tags

Attache une étiquette du catalogue à une conversation.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

L'étiquette doit déjà exister dans le catalogue de l'espace ; créez les étiquettes dans le tableau de bord.

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.
tag_id	integer	Obligatoire	L'identifiant d'une étiquette déjà présente dans le catalogue de l'espace.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/tags \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "tag_id": 4 }'

Réponse

{
  "attached": 4
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Un champ a échoué à la validation. L'objet errors le nomme.

DELETE /api/agent/conversations/{conversation}/tags/{tag}

Retire une étiquette d'une conversation.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.
tag	integer	Obligatoire	Chemin. L'identifiant de l'étiquette.

Requête

curl -X DELETE https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/tags/4 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "detached": 4
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	Aucun enregistrement de ce type dans cet espace de travail.

GET /api/agent/canned

Liste les réponses types utilisables par cet agent, les plus utilisées en tête.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Les réponses partagées et celles de cet agent, classées par fréquence d'utilisation.

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/agent/canned \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "canned": [
    {
      "id": 19,
      "title": "Courier claim opened",
      "shortcut": "/claim",
      "body": "I have opened a claim with the courier. You will hear from us within one working day."
    }
  ]
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

POST /api/agent/canned/{canned}/used

Enregistre qu'une réponse type a été insérée, pour que le classement continue d'apprendre.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit Aucune limite de route

Un agent ne peut marquer une réponse comme utilisée que si elle est partagée ou lui appartient.

Paramètres

Paramètre	Type	Obligatoire	Description
canned	integer	Obligatoire	Chemin. L'identifiant de la réponse type.

Requête

curl -X POST https://magizai.com/api/agent/canned/19/used \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "ok": true
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
403	La réponse type appartient à un autre agent et n'est pas partagée.
404	Aucune réponse type avec cet identifiant dans cet espace.

GET /api/agent/conversations/{conversation}/customer-context

Renvoie les commandes Shopify et l'abonnement Stripe du visiteur pour le panneau client.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Les deux intégrations se dégradent au lieu d'échouer. connected vaut false quand l'espace n'a pas connecté ce service ; shopify.orders est alors un tableau vide et stripe.data vaut null. stripe.data revient aussi sous la forme {"found": false} quand Stripe est connecté mais qu'aucun client ne correspond à l'e-mail du visiteur.

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.

Requête

curl https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/customer-context \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "email": "[email protected]",
  "shopify": {
    "connected": true,
    "orders": [
      {
        "name": "#8812",
        "total": "249.00 AED",
        "financial_status": "paid",
        "fulfillment_status": "fulfilled",
        "created_at": "Aug 1, 2026",
        "url": "https://acme.test/account/orders/5541882"
      }
    ]
  },
  "stripe": {
    "connected": true,
    "data": {
      "found": true,
      "customer": {
        "name": "Nadia Karim",
        "email": "[email protected]"
      },
      "subscriptions": [
        {
          "status": "active",
          "plan": "Care Plus",
          "amount": "29.00 AED",
          "renews": "Sep 1, 2026"
        }
      ]
    }
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	Aucun enregistrement de ce type dans cet espace de travail.

POST /api/agent/conversations/{conversation}/revenue

Définit ou efface la valeur d'affaire attribuée à une conversation.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit Aucune limite de route

Envoyez amount à null pour effacer la valeur. La devise reprend celle déjà présente sur la conversation, puis USD.

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.
amount	number	Facultatif	Valeur d'affaire en unités entières de devise, jusqu'à 100 000 000. Envoyez null pour l'effacer.
currency	string	Facultatif	Code de devise à trois lettres. Reprend la valeur déjà sur la conversation, puis USD.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/revenue \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "amount": 249, "currency": "AED" }'

Réponse

{
  "revenue_cents": 24900,
  "revenue_amount": 249.0,
  "revenue_currency": "AED",
  "revenue_label": "AED 249.00"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Un champ a échoué à la validation. L'objet errors le nomme.

POST /api/agent/conversations/{conversation}/lead

Enregistre comme prospect les coordonnées recueillies sur une conversation.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit Aucune limite de route

Nécessite qu'au moins un nom, e-mail ou téléphone ait déjà été recueilli sur la conversation, sans quoi il n'y a rien à enregistrer.

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/lead \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "lead": {
    "id": 233,
    "status": "new",
    "source": "manual"
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Aucun nom, e-mail ni téléphone n'a encore été recueilli sur cette conversation.

POST /api/agent/conversations/{conversation}/suggest

Rédige une réponse pour l'agent, appuyée sur les connaissances du chatbot.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit 30 requêtes toutes les 1 min, par utilisateur connecté

Coûte un appel d'IA. Quand il n'y a encore rien à répondre, ou qu'aucune clé de fournisseur n'est configurée, l'appel renvoie tout de même 200 avec suggestion à null. Conservez l'id renvoyé pour pouvoir signaler le résultat.

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.
draft	string	Facultatif	Ce que l'agent a déjà écrit, pour que la suggestion s'appuie dessus. Jusqu'à 4000 caractères.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/suggest \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "draft": "tell her the claim is open" }'

Réponse

{
  "id": 1204,
  "suggestion": "I have opened a claim with the courier for order #8812 and posted a replacement today. You will get a new tracking link by email within the hour."
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cet utilisateur a été atteinte.

POST /api/agent/conversations/{conversation}/enhance

Réécrit le brouillon de l'agent pour la grammaire ou le ton.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit 30 requêtes toutes les 1 min, par utilisateur connecté

Coûte un appel d'IA. Si le modèle ne peut pas améliorer le texte, l'original revient avec enhanced à false.

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.
body	string	Obligatoire	Le brouillon à réécrire. Jusqu'à 4000 caractères, et il ne peut pas être uniquement des espaces.
mode	string	Facultatif	fix, professional, friendly, concise ou expand. Par défaut fix.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/enhance \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "body": "claim is open, replacement sent today",
        "mode": "professional"
      }'

Réponse

{
  "text": "The claim is open and a replacement was posted today.",
  "enhanced": true
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Le brouillon ne contenait que des espaces.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cet utilisateur a été atteinte.

POST /api/agent/conversations/{conversation}/summary

Génère un court résumé interne de la conversation.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit 30 requêtes toutes les 1 min, par utilisateur connecté

Paramètres

Paramètre	Type	Obligatoire	Description
conversation	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.

Requête

curl -X POST https://magizai.com/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/summary \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "summary": "Replacement for order 8812 never arrived; courier shows delivered. Claim opened, replacement posted.",
  "summary_at": "a few seconds ago"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucun enregistrement de ce type dans cet espace de travail.
422	Aucun résumé n'a pu être généré pour l'instant.
429	La limite de route pour cet utilisateur a été atteinte.

POST /api/agent/suggestion/{suggestion}/outcome

Enregistre ce que l'agent a fait d'une suggestion de l'IA.

Authentification Jeton Bearer (agent) Droit du rôle handle-conversations Limite de débit 60 requêtes toutes les 1 min, par utilisateur connecté

Signalez generated, inserted, edited ou dismissed, pour que la qualité de l'assistant reste mesurable.

Paramètres

Paramètre	Type	Obligatoire	Description
suggestion	integer	Obligatoire	Chemin. L'identifiant renvoyé par le point suggest.
outcome	string	Obligatoire	generated, inserted, edited ou dismissed.

Requête

curl -X POST https://magizai.com/api/agent/suggestion/1204/outcome \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "outcome": "edited" }'

Réponse

{
  "ok": true
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404	Aucune suggestion avec cet identifiant dans cet espace.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cet utilisateur a été atteinte.

GET /api/agent/visitors

Liste toutes les personnes présentes sur les sites de l'espace en ce moment, y compris celles qui n'ont pas ouvert le chat.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

enabled indique si au moins un chatbot actif a les visiteurs en direct activés. poll_seconds est l'intervalle voulu par le serveur : lisez-le plutôt que d'en coder un en dur.

Paramètres

Paramètre	Type	Obligatoire	Description
limit	integer	Facultatif	Requête. Nombre de visiteurs à renvoyer. Borné entre 1 et 200 ; par défaut 100.

Requête

curl "https://magizai.com/api/agent/visitors?limit=50" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "visitors": [
    {
      "id": "90211",
      "visitor_id": "v_2c9a71b4e5",
      "session_token": "ps_5f1c0a9b8e7d5c4b3a2f1e0d",
      "label": "Nadia Karim",
      "short": "2C9A",
      "name": "Nadia Karim",
      "email": "[email protected]",
      "current_url": "https://acme.test/orders/8812",
      "current_title": "Order 8812",
      "entry_url": "https://acme.test/",
      "referrer": "https://www.google.com/",
      "country": "AE",
      "device": "mobile",
      "browser": "Safari",
      "os": "iOS",
      "page_views": 6,
      "seconds_on_site": 412,
      "last_seen_at": "2026-08-08T10:46:51+00:00",
      "started_at": "2026-08-08T10:39:59+00:00",
      "state": "chatting",
      "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
      "unread": 2,
      "chatbot": "Support bot"
    }
  ],
  "counts": {
    "total": 1,
    "browsing": 0,
    "chatting": 1,
    "waiting": 0
  },
  "poll_seconds": 25,
  "enabled": true
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

POST /api/agent/visitors/{visitor}/invite

Engage la conversation avec un visiteur en train de naviguer en lui envoyant le premier message.

Authentification Jeton Bearer (agent) Limite de débit 30 requêtes toutes les 1 min, par utilisateur connecté

Crée une conversation si le visiteur n'en a pas, la marque comme prise en charge par un humain pour que l'IA ne parle pas par-dessus vous, et renvoie 201 dans ce cas ; un visiteur avec un chat ouvert reçoit 200. Si aucune fenêtre de chat n'est ouverte, le message lui parvient au battement suivant.

Paramètres

Paramètre	Type	Obligatoire	Description
visitor	string	Obligatoire	Chemin. L'identifiant de visiteur issu de la liste des visiteurs en direct. Tronqué à 100 caractères.
message	string	Obligatoire	La phrase d'ouverture à envoyer. Jusqu'à 2000 caractères, et elle ne peut pas être uniquement des espaces.
chatbot_id	integer	Facultatif	Envoyer depuis ce chatbot. Omis, le chatbot du visiteur est préféré, puis n'importe lequel actif.

Requête

curl -X POST https://magizai.com/api/agent/visitors/v_2c9a71b4e5/invite \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "message": "Hi Nadia — I can see order 8812 on your screen. Want me to check it?" }'

Réponse

{
  "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
  "created": true,
  "delivery_within_seconds": 25,
  "message": {
    "id": 33140,
    "role": "agent",
    "content": "Hi Nadia — I can see order 8812 on your screen. Want me to check it?",
    "at": "10:52 AM"
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
404	L'identifiant de visiteur était vide après nettoyage.
409	Ce visiteur n'est plus sur le site.
422	L'espace n'a aucun chatbot actif pour envoyer le message.
429	La limite de route pour cet utilisateur a été atteinte.
500	Le chat n'a pas pu démarrer. Rien n'a été enregistré, vous pouvez réessayer sans risque.

GET /api/agent/push/vapid

Renvoie la clé publique dont un appareil a besoin avant de s'abonner aux notifications.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

configured vaut false sur un serveur où les notifications n'ont jamais été configurées, ce qui permet à une application de l'expliquer au lieu d'échouer à l'étape d'abonnement.

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/agent/push/vapid \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "configured": true,
  "public_key": "BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

POST /api/agent/push/subscribe

Enregistre un appareil pour recevoir les notifications.

Authentification Jeton Bearer (agent) Limite de débit 20 requêtes toutes les 1 min, par utilisateur connecté

Crée ou met à jour l'enregistrement d'après endpoint, car les navigateurs réémettent un abonnement chaque fois que le service de notification le renouvelle. Renvoyer un endpoint existant met à jour la ligne au lieu d'en créer une seconde.

Paramètres

Paramètre	Type	Obligatoire	Description
endpoint	url	Obligatoire	Le endpoint de notification émis par le navigateur. Doit être une URL https, jusqu'à 2048 caractères.
keys	object	Obligatoire	La paire de clés d'abonnement issue du navigateur.
keys.p256dh	string	Obligatoire	La clé p256dh de l'abonnement navigateur. Jusqu'à 255 caractères.
keys.auth	string	Obligatoire	Le secret auth de l'abonnement navigateur. Jusqu'à 255 caractères.
device_name	string	Facultatif	Un libellé pour cet appareil, affiché à côté du jeton. Jusqu'à 120 caractères.
platform	string	Facultatif	ios, android ou desktop.

Requête

curl -X POST https://magizai.com/api/agent/push/subscribe \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "endpoint": "https://web.push.apple.com/QK9x2m4Lp0",
        "keys": {
          "p256dh": "BJx7Qm2f0aLd9k3sVn1cRt8yUu5oWq4eZa6hGi2jKl0",
          "auth": "9fK2sQ7vN1cX3mLp"
        },
        "device_name": "Sara iPhone 15",
        "platform": "ios"
      }'

Réponse

{
  "ok": true,
  "id": 77,
  "devices": 2
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
422	Le endpoint n'est pas une URL https, il ne peut donc pas être un vrai service de notification.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cet utilisateur a été atteinte.
500	L'appareil n'a pas pu être enregistré pour les alertes.

DELETE /api/agent/push/subscribe

Supprime l'abonnement aux notifications de cet appareil.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Limité à l'appelant, pour qu'un endpoint divulgué ne serve pas à couper les alertes d'un autre agent.

Paramètres

Paramètre	Type	Obligatoire	Description
endpoint	string	Obligatoire	Le endpoint de notification à supprimer. Jusqu'à 2048 caractères.

Requête

curl -X DELETE https://magizai.com/api/agent/push/subscribe \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "endpoint": "https://web.push.apple.com/QK9x2m4Lp0" }'

Réponse

{
  "ok": true,
  "removed": 1
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
422	Un champ a échoué à la validation. L'objet errors le nomme.

POST /api/agent/push/test

Envoie une vraie alerte de test aux appareils de l'agent appelant.

Authentification Jeton Bearer (agent) Limite de débit 6 requêtes toutes les 1 min, par utilisateur connecté

Ignore volontairement les heures calmes et le mode ne pas déranger : qui demande un test de livraison veut savoir si cela fonctionne.

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl -X POST https://magizai.com/api/agent/push/test \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "ok": true,
  "result": {
    "sent": 2,
    "failed": 0,
    "pruned": 0
  }
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
422	Aucun appareil n'a reçu le test. Autorisez les notifications sur l'appareil puis réessayez.
429	La limite de route pour cet utilisateur a été atteinte.
503	Les notifications ne sont pas configurées sur ce serveur.

GET /api/agent/settings/notifications

Renvoie les préférences d'alerte de cet agent, sa disponibilité et ses appareils enregistrés.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Ces préférences sont appliquées côté serveur avant tout envoi : c'est donc le seul endroit où un agent décide si son téléphone sonne.

Paramètres

Ce point de terminaison ne prend aucun paramètre.

Requête

curl https://magizai.com/api/agent/settings/notifications \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

Réponse

{
  "settings": {
    "push_enabled": true,
    "sound_enabled": true,
    "vibrate_enabled": true,
    "email_enabled": false,
    "events": {
      "visitor_arrived":   { "push": false, "sound": null,     "label": "Visitor arrived",   "critical": false },
      "chat_started":      { "push": true,  "sound": "chime",  "label": "Chat started",      "critical": false },
      "visitor_message":   { "push": true,  "sound": "chime",  "label": "Visitor message",   "critical": false },
      "handoff_requested": { "push": true,  "sound": "urgent", "label": "Handoff requested", "critical": true  },
      "sla_breach":        { "push": true,  "sound": "urgent", "label": "SLA breach",        "critical": true  }
    },
    "sound_pack": "default",
    "volume": 70,
    "quiet_hours_start": "22:00",
    "quiet_hours_end": "07:00",
    "quiet_hours_tz": "Asia/Dubai",
    "dnd_until": null,
    "quiet_now": false,
    "dnd_now": false,
    "chatbot_filter": null,
    "only_my_conversations": false
  },
  "availability": "online",
  "push": {
    "configured": true,
    "public_key": "BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U",
    "devices": 2
  },
  "chatbots": [
    { "id": 7, "name": "Support bot" }
  ]
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.

PUT /api/agent/settings/notifications

Met à jour les préférences d'alerte et la disponibilité de cet agent.

Authentification Jeton Bearer (agent) Limite de débit Aucune limite de route

Mise à jour partielle : seuls les champs envoyés changent, et la carte events est fusionnée plutôt que remplacée, pour qu'une ancienne version de l'application ne puisse pas effacer un réglage qu'elle ignore. Les clés d'événement inconnues sont ignorées.

Paramètres

Paramètre	Type	Obligatoire	Description
push_enabled	boolean	Facultatif	Interrupteur général des notifications pour ce compte.
sound_enabled	boolean	Facultatif	Si les alertes émettent un son.
vibrate_enabled	boolean	Facultatif	Si les alertes font vibrer l'appareil.
email_enabled	boolean	Facultatif	Si les alertes sont aussi envoyées par e-mail.
events	object	Facultatif	Réglages par événement, indexés par événement : visitor_arrived, chat_started, visitor_message, handoff_requested, sla_breach. Fusionnés avec l'existant.
events.*.push	boolean	Facultatif	Si cet événement envoie une notification. Obligatoire pour chaque événement inclus.
events.*.sound	string	Facultatif	Nom du son pour cet événement, ou null pour le son par défaut. Jusqu'à 24 caractères.
sound_pack	string	Facultatif	Nom du pack de sons. Jusqu'à 24 caractères.
volume	integer	Facultatif	Volume des alertes, de 0 à 100.
quiet_hours_start	string	Facultatif	Début des heures calmes au format HH:MM, dans le fuseau de l'agent.
quiet_hours_end	string	Facultatif	Fin des heures calmes au format HH:MM. À envoyer avec le début.
quiet_hours_tz	string	Facultatif	Fuseau dans lequel les heures calmes sont lues, par exemple Asia/Dubai. Jusqu'à 64 caractères.
dnd_minutes	integer	Facultatif	Couper les alertes pendant ce nombre de minutes, de 0 à 1440. Envoyez 0 pour annuler.
chatbot_filter	array	Facultatif	N'alerter que sur ces identifiants de chatbot. Les identifiants hors de l'espace sont écartés, et un résultat vide supprime le filtre.
only_my_conversations	boolean	Facultatif	N'alerter que sur les conversations attribuées à cet agent.
availability	string	Facultatif	online, away ou offline.

Requête

curl -X PUT https://magizai.com/api/agent/settings/notifications \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "push_enabled": true,
        "volume": 70,
        "quiet_hours_start": "22:00",
        "quiet_hours_end": "07:00",
        "quiet_hours_tz": "Asia/Dubai",
        "events": {
          "visitor_arrived": { "push": false, "sound": null }
        },
        "availability": "online"
      }'

Réponse

{
  "settings": {
    "push_enabled": true,
    "sound_enabled": true,
    "vibrate_enabled": true,
    "email_enabled": false,
    "events": {
      "visitor_arrived":   { "push": false, "sound": null,     "label": "Visitor arrived",   "critical": false },
      "chat_started":      { "push": true,  "sound": "chime",  "label": "Chat started",      "critical": false },
      "visitor_message":   { "push": true,  "sound": "chime",  "label": "Visitor message",   "critical": false },
      "handoff_requested": { "push": true,  "sound": "urgent", "label": "Handoff requested", "critical": true  },
      "sla_breach":        { "push": true,  "sound": "urgent", "label": "SLA breach",        "critical": true  }
    },
    "sound_pack": "default",
    "volume": 70,
    "quiet_hours_start": "22:00",
    "quiet_hours_end": "07:00",
    "quiet_hours_tz": "Asia/Dubai",
    "dnd_until": null,
    "quiet_now": false,
    "dnd_now": false,
    "chatbot_filter": null,
    "only_my_conversations": false
  },
  "availability": "online"
}

Erreurs

Statut	Ce qui le déclenche
401	Aucun jeton valide n'a été envoyé.
403	Le compte ou l'espace de travail a été suspendu.
422	Les heures calmes exigent un début et une fin ; une demi-plage ne ferait rien.
422	Un champ a échoué à la validation. L'objet errors le nomme.
500	Les réglages n'ont pas pu être enregistrés.

Points du widget

Les points publics que le script d'intégration appelle depuis le navigateur de vos visiteurs. Ils sont documentés pour vous permettre de déboguer une installation ou de construire votre propre interface de chat. Ce n'est pas une API d'intégration et aucun n'accepte de jeton.

Chemin de base /widget/{key} · 7 points de terminaison

GET /widget/{key}/config

Renvoie la configuration publique d'un chatbot : apparence, accueil, formulaire de pré-chat et informations de connexion temps réel.

Authentification Aucune, public Limite de débit 60 requêtes toutes les 1 min, par adresse IP

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.

Requête

curl https://magizai.com/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/config \
  -H "Accept: application/json"

Réponse

{
  "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
  "name": "Support bot",
  "welcome_message": "Hi! How can I help you today?",
  "human_handoff_enabled": true,
  "branding": {
    "primary_color": "#4f46e5",
    "launcher_text": "Chat with us",
    "position": "right",
    "theme": "minimal",
    "logo_url": null,
    "avatar_url": null,
    "title": "Support bot",
    "subtitle": "We typically reply in a few seconds",
    "layout": "classic",
    "launcher": "bubble",
    "quick_replies": [],
    "agent_avatars": [],
    "composer_style": "full",
    "sound": true,
    "screen_share": false,
    "copilot": false,
    "auto_actions": true,
    "copilot_use_profile": false,
    "copilot_autostart": true,
    "live_visitors": true,
    "behavior_tracking": false,
    "recommend_mode": "reactive",
    "proactive": {
      "enabled": false,
      "message": "Hi! Anything I can help you find?",
      "delay": 20,
      "scroll": 0,
      "exit_intent": false,
      "url_contains": "",
      "frequency": "session"
    }
  },
  "powered_by": "MagizAI",
  "powered_by_url": "https://magizai.com",
  "pre_chat_form": {
    "enabled": true,
    "greeting": "Before we start, please introduce yourself.",
    "fields": {
      "name":  { "enabled": true,  "required": false },
      "email": { "enabled": true,  "required": true  },
      "phone": { "enabled": false, "required": false }
    }
  },
  "realtime": {
    "key": "reverbappkey",
    "host": "realtime.acme.test",
    "port": 443,
    "scheme": "https"
  }
}

Erreurs

Statut	Ce qui le déclenche
404	Aucun chatbot actif ne porte cette clé publique. Un chatbot désactivé répond de la même façon.
429	La limite de route pour cette adresse IP a été atteinte.

POST /widget/{key}/boot

Ouvre ou reprend la conversation d'un visiteur et renvoie la transcription en cours.

Authentification Aucune, public Limite de débit 30 requêtes toutes les 1 min, par adresse IP

Passez un conversation_id pour reprendre. S'il ne correspond pas à l'identifiant de visiteur envoyé, ou si cette conversation était close, une nouvelle est ouverte plutôt que l'appel échoue.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
visitor_id	string	Obligatoire	L'identifiant que votre widget attribue à un visiteur et conserve pour la session. Jusqu'à 100 caractères.
conversation_id	uuid	Facultatif	Une conversation existante à poursuivre. Omettez-le pour en démarrer une nouvelle.
meta	object	Facultatif	Contexte sur le visiteur et la page. meta.visitor peut porter le nom, l'e-mail et le téléphone issus de votre formulaire de pré-chat.
identity	string	Facultatif	Un jeton d'identité signé par votre propre serveur. Il est vérifié avant que quoi que ce soit ne soit cru. Jusqu'à 4000 caractères.

Requête

curl -X POST https://magizai.com/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/boot \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "meta": {
          "page": "https://acme.test/orders/8812",
          "visitor": { "name": "Nadia Karim", "email": "[email protected]" }
        }
      }'

Réponse

{
  "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
  "status": "bot",
  "handoff_state": "bot_active",
  "wait_remaining": null,
  "messages": [
    {
      "id": 33126,
      "role": "visitor",
      "content": "I still have not received the replacement.",
      "at": "2026-08-08T10:41:04+00:00"
    },
    {
      "id": 33127,
      "role": "assistant",
      "content": "Let me check that order for you.",
      "at": "2026-08-08T10:41:07+00:00"
    }
  ]
}

Erreurs

Statut	Ce qui le déclenche
404	Aucun chatbot actif ne porte cette clé publique. Un chatbot désactivé répond de la même façon.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cette adresse IP a été atteinte.

POST /widget/{key}/stream

Envoie un message visiteur et diffuse la réponse de l'IA en Server-Sent Events.

Authentification Aucune, public Limite de débit 20 requêtes toutes les 1 min, par adresse IP

La réponse est un text/event-stream, pas du JSON. Les événements arrivent dans l'ordre : meta d'abord, puis un nombre quelconque d'événements delta, éventuellement recommendations, et enfin done ou error. Un refus avant le début de la diffusion est une réponse d'erreur JSON classique.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
visitor_id	string	Obligatoire	L'identifiant que votre widget attribue à un visiteur et conserve pour la session. Jusqu'à 100 caractères.
message	string	Obligatoire	Le message du visiteur. Jusqu'à 4000 caractères, et il ne peut pas être uniquement des espaces.
conversation_id	uuid	Facultatif	Une conversation existante à poursuivre. Omettez-le pour en démarrer une nouvelle.
meta	object	Facultatif	Contexte sur le visiteur et la page. meta.visitor peut porter le nom, l'e-mail et le téléphone issus de votre formulaire de pré-chat.
identity	string	Facultatif	Un jeton d'identité signé par votre propre serveur. Il est vérifié avant que quoi que ce soit ne soit cru. Jusqu'à 4000 caractères.

Requête

curl -N -X POST https://magizai.com/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
        "message": "Where is my replacement?"
      }'

Réponse

event: meta
data: {"conversation_id":"6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91","visitor_message_id":33128,"status":"bot"}

event: delta
data: {"delta":"Your replacement "}

event: delta
data: {"delta":"was posted this morning."}

event: recommendations
data: {"products":[{"id":41,"name":"Express delivery","price":"AED 25.00","currency":"AED","url":"https://acme.test/express","buy_url":"https://acme.test/express","image_url":null,"description":"Next-working-day delivery across the UAE.","in_stock":true}]}

event: done
data: {"message_id":33129,"source":"ai","sources":[{"title":"Shipping policy","url":"https://acme.test/shipping"}]}

Erreurs

Statut	Ce qui le déclenche
404	Aucun chatbot actif ne porte cette clé publique. Un chatbot désactivé répond de la même façon.
422	Le message ne contenait que des espaces.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cette adresse IP a été atteinte.

POST /widget/{key}/chat/reset

Clôt la conversation en cours du visiteur pour que le widget en démarre une neuve.

Authentification Aucune, public Limite de débit 30 requêtes toutes les 1 min, par adresse IP

Idempotent et vérifié en propriété. Il clôt la conversation côté serveur ; le widget en démarre ensuite une neuve, et c'est cela qui efface le contexte.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
visitor_id	string	Obligatoire	L'identifiant que votre widget attribue à un visiteur et conserve pour la session. Jusqu'à 100 caractères.
conversation_id	uuid	Obligatoire	La conversation à clore. Elle doit appartenir à l'identifiant de visiteur envoyé.

Requête

curl -X POST https://magizai.com/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/chat/reset \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91"
      }'

Réponse

{
  "ok": true
}

Erreurs

Statut	Ce qui le déclenche
404	Aucun chatbot actif ne porte cette clé publique. Un chatbot désactivé répond de la même façon.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cette adresse IP a été atteinte.

GET /widget/{key}/conversations/{conversationId}/history

Interroge une conversation pour les nouveaux messages, y compris les réponses d'un agent humain.

Authentification Aucune, public Limite de débit 60 requêtes toutes les 1 min, par adresse IP

Passez after avec le plus grand identifiant de message que vous détenez pour ne récupérer que la nouveauté.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
conversationId	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.
visitor_id	string	Obligatoire	L'identifiant que votre widget attribue à un visiteur et conserve pour la session. Jusqu'à 100 caractères.
after	integer	Facultatif	Requête. Ne renvoie que les messages dont l'identifiant est supérieur à cette valeur.

Requête

curl "https://magizai.com/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/history?visitor_id=v_2c9a71b4e5&after=33127" \
  -H "Accept: application/json"

Réponse

{
  "status": "agent",
  "handoff_state": "human_connected",
  "wait_remaining": null,
  "messages": [
    {
      "id": 33131,
      "role": "agent",
      "content": "I have opened a claim with the courier and posted a replacement today.",
      "at": "2026-08-08T10:47:20+00:00"
    }
  ]
}

Erreurs

Statut	Ce qui le déclenche
404	Aucune conversation avec cet identifiant pour ce chatbot et cet identifiant de visiteur.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cette adresse IP a été atteinte.

POST /widget/{key}/conversations/{conversationId}/rate

Enregistre un pouce en haut ou en bas sur une réponse de l'IA.

Authentification Aucune, public Limite de débit 60 requêtes toutes les 1 min, par adresse IP

Envoyez rating à 0 pour annuler un vote précédent. Un pouce en bas est aussi enregistré comme lacune de connaissance à corriger par l'espace de travail.

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
conversationId	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.
visitor_id	string	Obligatoire	L'identifiant que votre widget attribue à un visiteur et conserve pour la session. Jusqu'à 100 caractères.
message_id	integer	Obligatoire	Le message de l'assistant qui est évalué.
rating	integer	Obligatoire	1 pour un pouce en haut, -1 pour un pouce en bas, 0 pour annuler un vote.

Requête

curl -X POST https://magizai.com/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/rate \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "message_id": 33129,
        "rating": -1
      }'

Réponse

{
  "ok": true,
  "rating": -1
}

Erreurs

Statut	Ce qui le déclenche
404	La conversation est introuvable, ou l'identifiant de message n'y est pas un message d'assistant.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cette adresse IP a été atteinte.

POST /widget/{key}/conversations/{conversationId}/csat

Enregistre une note de satisfaction pour toute la conversation.

Authentification Aucune, public Limite de débit 10 requêtes toutes les 1 min, par adresse IP

Paramètres

Paramètre	Type	Obligatoire	Description
key	string	Obligatoire	Chemin. La clé publique du chatbot, la même valeur que dans le code d'intégration.
conversationId	uuid	Obligatoire	Chemin. L'identifiant public de la conversation, un UUID.
visitor_id	string	Obligatoire	L'identifiant que votre widget attribue à un visiteur et conserve pour la session. Jusqu'à 100 caractères.
score	integer	Obligatoire	Note de satisfaction de 1 à 5.
comment	string	Facultatif	Commentaire libre. Jusqu'à 2000 caractères.

Requête

curl -X POST https://magizai.com/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/csat \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "score": 5,
        "comment": "Sorted in two minutes."
      }'

Réponse

{
  "ok": true
}

Erreurs

Statut	Ce qui le déclenche
404	Aucune conversation avec cet identifiant pour ce chatbot et cet identifiant de visiteur.
422	Un champ a échoué à la validation. L'objet errors le nomme.
429	La limite de route pour cette adresse IP a été atteinte.

Points du widget non documentés ici

Ils existent et le script d'intégration les utilise, mais ils sont internes au widget plutôt que destinés à être appelés directement. Ils sont listés pour que vous sachiez qu'ils ont été écartés volontairement.

Méthode	Point de terminaison	Pourquoi
POST	/widget/{key}/upload	Envoi de fichier multipart, lié au flux de pièces jointes du widget et à ses règles de stockage.
POST	/widget/{key}/request-human	Prise en charge d'un transfert hors ligne. Il envoie des alertes par e-mail et WhatsApp à l'espace de travail, il reste donc derrière le flux du widget.
POST	/widget/{key}/conversions	Balise de conversion pour la chaîne de reporting, utile uniquement avec le script de suivi du widget.
POST	/widget/{key}/track	Balise de comportement pour les événements page, produit et panier. Activée par chatbot et entièrement façonnée par le widget.
POST	/widget/{key}/presence	Battement de cœur des visiteurs en direct. Sa cadence est liée à l'intervalle de balise du widget.
POST	/widget/{key}/assist	Guidage du copilote sur la page. La charge utile est un instantané de la page visiteur produit par le widget.

Il vous manque quelque chose ?

Dites-nous ce que vous construisez et nous vous indiquerons le bon point de terminaison, ou nous en ajouterons un.

Parlez-nous Parcourir le centre d'aide