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 basehttps://magiz.ai
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.
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.
Le widget sur votre site
Une seule balise script installe l'assistant sur toutes vos pages. Tout ce qui suit est facultatif : le widget fonctionne avec la clé seule.
Obligatoire. La clé publique de votre chatbot, dans Chatbots puis Installation.
data-open="load"
Ouvre le panneau dès le chargement de la page. À réserver à une page entièrement dédiée à l'assistant, par exemple une page discuter avec l'IA.
data-launcher
Impose le style du lanceur pour cette page, au-dessus du réglage du tableau de bord. Valeurs acceptées : bubble ou teaser. Utile quand le teaser masque un formulaire.
data-identity
Un jeton d'identité signé pour la personne qui consulte la page. Voir ci-dessous.
data-cookie-domain
Portée du cookie qui conserve une conversation entre sous-domaines, par exemple .example.com. Utile seulement quand le domaine a un suffixe composé comme .co.uk et que la détection automatique se trompe.
data-lang
La langue des textes de la fenêtre de chat et son sens d'écriture, pour des visiteurs qui lisent une autre langue que la page : en, fr ou ar. Sans lui, la fenêtre suit la langue de la page, puis celle du navigateur.
data-consent="wait"
Mettez wait quand votre bandeau de cookies décide. Tant que votre page n'appelle pas MagizAI.consent(true), le widget n'enregistre rien dans le navigateur du visiteur (aucun cookie d'identifiant, rien dans localStorage ni sessionStorage) et n'envoie aucune donnée de visite ni de navigation. Le visiteur peut quand même ouvrir le chat avant cela ; il fonctionne alors pour cette page seulement.
Piloter le widget depuis votre page
Le script expose un petit objet sur window une fois chargé. Chaque méthode peut être appelée avant même que le visiteur ait ouvert la discussion.
// Open the panel, optionally with the question already asked.
MagizAI.open();
MagizAI.open('Which plan suits a site with 20,000 visits a month?');
// Close it again.
MagizAI.close();
// Call this when the visitor signs out: it ends this browser's conversation
// and forgets whose it was, so the next person starts anonymously.
MagizAI.logout();
// Record a sale the chat contributed to, for the revenue report.
MagizAI.trackConversion(149.00, 'USD');
// With your cookie banner (data-consent="wait" on the script tag):
// the visitor agreed, so the widget may store its visitor ID...
MagizAI.consent(true);
// ...or said no: what the widget stored leaves this browser.
MagizAI.consent(false);
MagizAI.open() avec une question est ce qui fait fonctionner un bouton Poser une question sur cette offre : le panneau s'ouvre et la question est déjà envoyée, donc le visiteur voit une réponse au lieu d'un champ vide. Les sites installés avant le changement de nom peuvent continuer d'appeler window.ElyAgents, qui est le même objet.
MagizAI.consent(true) enregistre l'identifiant du visiteur et démarre les visiteurs en direct et le suivi de navigation, chacun là où il est activé et si le navigateur n'envoie pas Do Not Track. MagizAI.consent(false) les arrête pour cette page et retire ce que le widget a enregistré dans ce navigateur : l'identifiant du visiteur, le lien vers la conversation, les coordonnées données par le visiteur et les préférences du widget ; un chat ouvert continue jusqu'à ce que la page soit quittée. Le widget ne retient pas la réponse : appelez-la sur chaque page dès que votre bandeau la connaît ; un appel fait avant le chargement du widget est conservé. Sans bandeau, le réglage du chatbot « N'enregistrer un identifiant de visiteur qu'après l'ouverture du chat » retient tout de la même façon jusqu'à l'ouverture du chat.
Identité visiteur signée
Sans elle, l'assistant considère tout le monde comme anonyme et refuse de parler d'un compte. Avec elle, il sait qui pose la question et peut répondre sur ses propres commandes, factures, services ou tickets. Votre backend signe un jeton compact en HS256 avec le secret d'identité du chatbot ; le navigateur ne fait que le transporter.
<?php
// Server-side, in the page your signed-in customer is served. Never in the browser:
// whoever holds the secret can impersonate any of your customers.
$secret = getenv('MAGIZAI_IDENTITY_SECRET'); // Chatbots → Install → Signed visitor identity
$b64 = fn (array $a) => rtrim(strtr(base64_encode(json_encode($a)), '+/', '-_'), '=');
$header = $b64(['alg' => 'HS256', 'typ' => 'JWT']);
$payload = $b64([
'sub' => (string) $user->id, // your id for this person
'external_id' => (string) $user->id,
'email' => $user->email,
'name' => $user->name,
'plan' => $user->plan, // optional, shown to your agents
'company' => $user->company_name, // optional
'locale' => 'en', // optional
'iat' => time(),
'exp' => time() + 3600, // 24 hours is the hard ceiling
]);
$sig = rtrim(strtr(base64_encode(hash_hmac('sha256', "$header.$payload", $secret, true)), '+/', '-_'), '=');
$token = "$header.$payload.$sig";
?>
<script>window.MagizAIIdentity = "<?= $token ?>";</script>
<script src="https://magiz.ai/widget.js" data-key="cv_9f2a4c7e1b6d3a8f5c0e2b4d" defer></script>
Paramètre
Description
sub
Obligatoire. Votre identifiant pour cette personne. La conversation et sa mémoire y sont rattachées. Jamais "0" : un jeton qui désigne "0" est refusé.
external_id
Alias facultatif de sub, accepté pour qu'un backend envoie le champ dont il dispose déjà. La même règle s'applique : jamais "0".
email
Sert à rapprocher le visiteur de ses commandes, tickets et discussions passées, et s'affiche pour vos agents.
name
Affiché à vos agents et utilisé par l'assistant pour saluer le visiteur.
plan
Facultatif. Le libellé que vous utilisez pour le niveau ou le segment. Vos agents le voient sur la fiche client.
company
Facultatif. Le nom du compte ou de l'organisation.
locale
Facultatif. Code de langue à deux lettres, utilisé quand le chatbot suit l'utilisateur connecté plutôt que le navigateur.
iat / exp
Émission et expiration, en secondes. Un jeton n'est jamais accepté au-delà de 24 heures, quelle que soit la valeur d'exp. Générez-en un neuf à chaque chargement de page.
Signez côté serveur et n'envoyez jamais le secret au navigateur : qui le détient peut se faire passer pour n'importe lequel de vos clients. Appelez MagizAI.logout() à la déconnexion, pour qu'un poste partagé ne transmette pas la conversation précédente à la personne suivante.
Webhooks
La seule partie de la plateforme qui vous appelle. Ajoutez une adresse dans Automatisations, onglet Webhooks, choisissez les événements qui vous intéressent, et nous envoyons un POST JSON signé à votre URL quand ils se produisent.
Événement
Ce qui le déclenche
conversation.created
Un visiteur a ouvert une conversation, avant tout échange.
message.received
Un visiteur a envoyé un message.
ai.replied
L'assistant a répondu. Utile pour journaliser ce qui a été dit à un client.
keyword.matched
Un mot-clé que vous avez défini est apparu dans un message visiteur.
handoff.requested
La conversation demande un humain, que le visiteur l'ait demandé ou que l'assistant ait escaladé. C'est l'événement à brancher sur vos alertes.
handoff.followup
Un visiteur a laissé ses coordonnées pour que votre équipe lui réponde plus tard. Envoyé à la place de handoff.requested quand la conversation attend déjà une personne, ou quand la dernière demande est restée sans réponse. Branchez-le aussi sur vos alertes.
conversation.resolved
Une conversation a été close, par un agent ou par l'assistant. Le déclencheur habituel pour clore votre propre ticket.
tag.added
Une étiquette a été posée sur une conversation.
lead.captured
Des coordonnées ont été recueillies. Le déclencheur habituel pour créer une fiche dans votre CRM.
lead.request
Un visiteur a confirmé dans la conversation une demande pour votre équipe, comme un rappel ou un devis. Le contact et sa demande arrivent sous data.lead.
conversion.recorded
Un chiffre d'affaires a été attribué à une conversation.
action.executed
L'assistant a exécuté une de vos actions, par exemple une compétence ou un outil connecté.
booking.created
Une réservation a été faite et ne demande pas de validation. Elle arrive sous data.booking, sans lien permettant de la modifier.
booking.requested
Une demande de réservation est arrivée et attend que votre équipe la confirme ou la refuse.
booking.confirmed
Une demande de réservation a été confirmée.
booking.declined
Une demande de réservation a été refusée.
booking.cancelled
Une réservation a été annulée, par le client ou par votre équipe.
booking.rescheduled
Une réservation a été déplacée à un autre horaire.
booking.completed
Une réservation a été marquée comme terminée.
booking.no_show
Un client ne s'est pas présenté à sa réservation.
Chaque envoi a la même enveloppe : le nom de l'événement, l'horodatage, et un objet data. Aucun enregistrement Eloquent n'est sérialisé tel quel : data ne contient que des champs simples, et une conversation arrive toujours dans data.conversation avec son public_id.
Chaque requête porte X-Signature: sha256= suivi d'un HMAC des octets exacts envoyés, avec le secret de votre endpoint comme clé. Vérifiez-le avant de faire confiance au corps, et comparez en temps constant.
// Node / Express. Verify against the RAW body, before any JSON parsing:
// re-serialising changes the bytes and the signature will never match.
app.post('/hooks/magizai', express.raw({ type: 'application/json' }), (req, res) => {
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.MAGIZAI_WEBHOOK_SECRET)
.update(req.body)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(req.get('X-Signature') || '');
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);
const { event, data } = JSON.parse(req.body.toString('utf8'));
// Answer first, work afterwards: anything slower than 10 seconds counts as a failure.
res.sendStatus(200);
queue.push({ event, data });
});
Règle
Description
HTTPS public uniquement
L'URL doit résoudre vers une adresse publique. Les adresses internes et de bouclage sont refusées, la connexion est épinglée à l'adresse vérifiée, et les redirections ne sont pas suivies.
Délai de 10 secondes
Répondez 2xx dès que vous avez la charge utile et traitez ensuite. Au-delà, l'envoi est compté comme un échec.
3 tentatives
Un échec ou une réponse hors 2xx est réessayé jusqu'à deux fois, à quelques secondes ou une minute d'intervalle, soit trois tentatives en tout. Après la troisième, l'envoi reste marqué en échec dans le journal. Une adresse refusée par le contrôle d'adresse publique n'est pas réessayée.
Aucune garantie d'ordre
Les envois passent par une file : deux événements peuvent arriver dans le désordre et une nouvelle tentative peut arriver deux fois. Traitez la charge utile comme un fait à appliquer plutôt qu'une étape à rejouer, et indexez sur public_id.
Chaque envoi est journalisé
Statut, code de réponse et les 2000 premiers caractères de votre réponse sont conservés, et le bouton de test envoie une charge utile d'exemple. Consultez ce journal en premier quand quelque chose n'arrive pas.
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·9 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
Aucun enregistrement de ce type dans cet espace de travail.
GET/api/v1/chatbots/{key}/knowledge
Liste les documents d'un chatbot, du plus récent au plus ancien, sous forme paginée.
Authentification Jeton Bearer (api)Limite de débit Aucune limite de route
Les pages issues de l'exploration d'une URL sont exclues, afin que le total corresponde à ce qu'un administrateur voit sur l'écran Connaissances. Filtrez par source_url_prefix pour ne demander que les documents poussés par votre propre intégration : c'est ainsi qu'une synchronisation compare ce qu'elle a envoyé avec ce qui est réellement en place.
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
Facultatif
Ne renvoie que ce type : text, qa, url ou file.
source_url_prefix
string
Facultatif
Ne renvoie que les documents dont l'adresse commence ainsi.
per_page
integer
Facultatif
Requête. Lignes par page. Par défaut 20, plafonné à 100.
Aucun enregistrement de ce type dans cet espace de travail.
422
Un champ a échoué à la validation. L'objet errors le nomme.
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ôlemanage-contentLimite 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.
source_url
string
Facultatif
Obligatoire quand type vaut url. La page à explorer, jusqu'à 2048 caractères.
visibility
string
Facultatif
public ou customer. Un document customer n'est utilisé que lorsque le visiteur est identifié par un jeton signé.
Requête
curl -X POST https://magiz.ai/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",
"source_url": "https://example.com/help/refund-policy",
"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."
}'
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.
DELETE/api/v1/chatbots/{key}/knowledge
Supprime des documents envoyés : celui situé à source_url, ou tout ce qui se trouve sous url_prefix sauf les adresses listées dans keep.
Authentification Jeton Bearer (api)Droit du rôlemanage-contentLimite de débit Aucune limite de route
C'est ainsi qu'une synchronisation retire les articles supprimés à la source : envoyez dans keep les adresses que vous avez encore, et tout le reste envoyé sous ce préfixe disparaît. Les pages explorées, les fichiers téléversés et les documents ajoutés à la main ne sont jamais touchés.
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_url
string
Facultatif
Supprime le seul document envoyé avec cette adresse. Obligatoire si url_prefix est absent.
url_prefix
string
Facultatif
Supprime tous les documents envoyés dont l'adresse commence ainsi. Doit comporter un chemin, pas seulement un domaine.
keep
array
Facultatif
Adresses à conserver avec url_prefix. Jusqu'à 5000.
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
url_prefix n'a pas de chemin. Un domaine nu effacerait tous les documents du chatbot, la requête est donc refusée.
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ôlehandle-conversationsLimite 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://magiz.ai/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.
{
"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 IA
L'IA de MagizAI pour vos propres logiciels, sans chatbot : rédiger, reformuler, résumer, extraire, classer, traduire et répondre aux questions avec ce que votre entreprise a appris à l'IA. Elle peut aussi lancer une exécution d'un des agents IA de l'espace et lire son déroulement. Un gestionnaire de l'espace active l'application API IA, puis crée un jeton en cochant « Peut utiliser l'API IA » dans Paramètres, Jetons d'API. Chaque appel compte comme un message IA du forfait, comme une réponse du chat, et comme un des appels à l'API IA du mois prévus par le forfait. Chaque erreur porte un code stable : app_off, no_ability, invalid, health_off, cap, rate_limited, no_ai, failed, not_found, agents_off, agents_stopped ou agent_unavailable. N'envoyez pas de dossiers de santé, sauf si l'espace a activé l'IA pour les données de santé, et marquez alors l'appel avec contains_health_data.
Chemin de base/api/v1/ai·5 points de terminaison
POST/api/v1/ai/complete
Exécute une tâche d'IA sur le texte envoyé. Renvoie du texte, ou des champs pour extract et classify.
Authentification Jeton Bearer (api)Droit du rôleaiLimite de débit 60 requêtes toutes les 1 min, par jeton
Le résultat est une suggestion : vérifiez-le avant qu'il n'atteigne un client ou ne modifie un dossier. Pour extract, un champ que le texte ne donne pas vaut null. Pour classify, chaque champ contient une de ses options, ou null.
Paramètres
Paramètre
Type
Obligatoire
Description
purpose
string
Obligatoire
Une valeur parmi write, rewrite, summarise, extract, classify, translate, answer.
input
string
Obligatoire
Le texte à traiter : la consigne pour write, le texte avec sa question pour answer. Jusqu'à 10000 caractères.
language
string
Facultatif
Écrire dans cette langue, sous forme de code comme fr ou de nom comme French. Obligatoire pour translate. Par défaut : la langue du texte.
tone
string
Facultatif
Une valeur parmi neutral, friendly, formal, warm.
fields
array
Facultatif
Pour extract et classify : jusqu'à 25 noms de champs, ou des objets avec name, description et options. Classify exige des options pour chaque champ.
contains_health_data
boolean
Facultatif
true quand le texte contient des données de santé. Refusé sauf si l'espace a activé l'IA pour les données de santé.
Requête
curl -X POST https://magiz.ai/api/v1/ai/complete \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"purpose": "extract",
"input": "Hi, this is Sara Bell. My order A-1055 has not arrived in Dubai yet.",
"fields": ["name", "order_number", "city"]
}'
app_off : l'application API IA est désactivée pour l'espace.
403
no_ability : le jeton a été créé sans la capacité ai, ou son propriétaire ne peut plus gérer l'espace.
403
health_off : l'appel est marqué contains_health_data et l'IA pour les données de santé est désactivée.
422
invalid : un champ n'a pas passé la validation. L'objet errors le nomme.
429
cap : les appels à l'API IA du mois, ou les messages IA du forfait, sont épuisés.
429
rate_limited : trop d'appels avec ce jeton en une minute. Retry-After indique quand réessayer.
502
failed : l'IA n'a pas donné de réponse utilisable. Réessayez.
503
no_ai : l'espace n'a pas d'IA qui peut répondre maintenant (pas de clé IA valide, ou l'espace n'est pas actif).
POST/api/v1/ai/answer
Répond à une question avec les connaissances apprises par l'espace et liste les sources utilisées.
Authentification Jeton Bearer (api)Droit du rôleaiLimite de débit 30 requêtes toutes les 1 min, par jeton
Ne lit que les passages publics, sauf si audience vaut staff. knowledge indique ce que la recherche a trouvé : used, none_found, no_knowledge ou unavailable. Quand rien ne correspond, le modèle a pour consigne de le dire plutôt que de deviner.
Paramètres
Paramètre
Type
Obligatoire
Description
question
string
Obligatoire
La question. Jusqu'à 2000 caractères.
language
string
Facultatif
Écrire dans cette langue, sous forme de code comme fr ou de nom comme French. Obligatoire pour translate. Par défaut : la langue du texte.
audience
string
Facultatif
public (par défaut) ne lit que les passages publics. staff lit aussi les passages pour les clients connectés et les notes internes.
contains_health_data
boolean
Facultatif
true quand le texte contient des données de santé. Refusé sauf si l'espace a activé l'IA pour les données de santé.
Requête
curl -X POST https://magiz.ai/api/v1/ai/answer \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"question": "Do you deliver to Dubai, and how long does it take?"
}'
Réponse
{
"answer": "Yes. Orders to Dubai arrive in two to four working days with DHL Express.",
"knowledge": "used",
"sources": [
{
"title": "Shipping and delivery",
"url": "https://acme.test/shipping"
}
]
}
Erreurs
Statut
Ce qui le déclenche
401
Aucun jeton valide n'a été envoyé.
403
app_off : l'application API IA est désactivée pour l'espace.
403
no_ability : le jeton a été créé sans la capacité ai, ou son propriétaire ne peut plus gérer l'espace.
403
health_off : l'appel est marqué contains_health_data et l'IA pour les données de santé est désactivée.
422
invalid : un champ n'a pas passé la validation. L'objet errors le nomme.
429
cap : les appels à l'API IA du mois, ou les messages IA du forfait, sont épuisés.
429
rate_limited : trop d'appels avec ce jeton en une minute. Retry-After indique quand réessayer.
502
failed : l'IA n'a pas donné de réponse utilisable. Réessayez.
503
no_ai : l'espace n'a pas d'IA qui peut répondre maintenant (pas de clé IA valide, ou l'espace n'est pas actif).
GET/api/v1/ai/agents
Liste les agents actifs de l'espace qu'un jeton peut lancer.
Authentification Jeton Bearer (api)Droit du rôleaiLimite de débit 60 requêtes toutes les 1 min, par jeton
Un agent qui traite des données de santé n'est pas listé : il ne s'exécute jamais par l'API. can_act vaut true quand l'agent peut demander des actions, qui attendent un responsable dans le tableau de bord. L'application Agents doit être activée.
app_off : l'application API IA est désactivée pour l'espace.
403
agents_off : l'application Agents est désactivée pour l'espace.
403
no_ability : le jeton a été créé sans la capacité ai, ou son propriétaire ne peut plus gérer l'espace.
429
rate_limited : trop d'appels avec ce jeton en une minute. Retry-After indique quand réessayer.
POST/api/v1/ai/agents/{id}/runs
Lance une exécution d'un agent avec une tâche. Répond aussitôt avec l'exécution, ou quand elle se termine dans les wait secondes.
Authentification Jeton Bearer (api)Droit du rôleaiLimite de débit 10 requêtes toutes les 1 min, par jeton
L'exécution garde toutes les règles de l'application Agents : les limites de l'agent, les plafonds de coût et l'arrêt général. Chaque appel au modèle compte comme un appel à l'API IA et un message IA. Le statut 202 signifie que l'exécution continue : lisez-la avec GET /api/v1/ai/runs/{id}. Les actions et les brouillons attendent un responsable sur la page de l'exécution dans le tableau de bord (dashboard_url) ; l'API ne peut pas les approuver. L'application Agents doit être activée.
Paramètres
Paramètre
Type
Obligatoire
Description
id
integer
Obligatoire
Chemin. L'identifiant de l'agent, donné par GET /api/v1/ai/agents.
task
string
Obligatoire
Ce que l'agent doit faire. Jusqu'à 4000 caractères.
inputs
object
Facultatif
Jusqu'à 20 valeurs nommées, par exemple {"invoice": "INV-0107"}. Les noms utilisent des lettres, des chiffres et _. L'agent les lit comme des données, jamais comme des instructions.
wait
integer
Facultatif
Secondes pendant lesquelles l'appel attend la fin de l'exécution, de 0 à 25. Par défaut 0 : une réponse immédiate avec le statut 202.
Requête
curl -X POST https://magiz.ai/api/v1/ai/agents/12/runs \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"task": "Check what Ananya Rao owes and draft a polite reminder.",
"inputs": {"customer": "Ananya Rao"},
"wait": 20
}'
Réponse
{
"run": {
"id": 845,
"agent": {
"id": 12,
"name": "Billing desk",
"version": 3
},
"status": "done",
"ended": "done",
"output": "Ananya Rao owes INR 4,500 on invoice INV-0107, due on 20 October. I saved a reminder email as a draft for you to check.",
"approval": "pending",
"actions": [],
"drafts": 1,
"dashboard_url": "https://magiz.ai/agents/runs/845",
"usage": {
"model_calls": 3,
"tool_calls": 2,
"tokens_in": 4120,
"tokens_out": 310,
"cost_usd": "0.004380"
},
"started_at": "2026-10-16T09:12:03.120Z",
"finished_at": "2026-10-16T09:12:09.874Z"
}
}
Erreurs
Statut
Ce qui le déclenche
401
Aucun jeton valide n'a été envoyé.
403
app_off : l'application API IA est désactivée pour l'espace.
403
agents_off : l'application Agents est désactivée pour l'espace.
403
no_ability : le jeton a été créé sans la capacité ai, ou son propriétaire ne peut plus gérer l'espace.
404
not_found : aucun agent avec cet identifiant dans l'espace.
409
agent_unavailable : l'agent est archivé, ou traite des données de santé.
409
agents_stopped : un gestionnaire de l'espace a arrêté tous les agents.
422
invalid : un champ n'a pas passé la validation. L'objet errors le nomme.
429
cap : les appels à l'API IA du mois ou les messages IA du forfait sont épuisés, ou le plafond de coût des agents pour aujourd'hui est atteint.
429
rate_limited : trop d'appels avec ce jeton en une minute. Retry-After indique quand réessayer.
GET/api/v1/ai/runs/{id}
Lit une exécution lancée par l'API IA : son état, sa réponse, ce qui attend un responsable et ce qu'elle a consommé.
Authentification Jeton Bearer (api)Droit du rôleaiLimite de débit 120 requêtes toutes les 1 min, par jeton
status vaut running, waiting, done, stopped ou failed. ended indique comment elle s'est terminée, par exemple done, waiting, step_limit, time_limit, cap ou rejected. approval vaut pending tant qu'un responsable doit décider. Les exécutions lancées depuis le tableau de bord, un flux ou une conversation ne peuvent pas être lues ici.
Paramètres
Paramètre
Type
Obligatoire
Description
id
integer
Obligatoire
Chemin. L'identifiant de l'exécution, donné par l'appel qui l'a lancée.
app_off : l'application API IA est désactivée pour l'espace.
403
agents_off : l'application Agents est désactivée pour l'espace.
403
no_ability : le jeton a été créé sans la capacité ai, ou son propriétaire ne peut plus gérer l'espace.
404
not_found : aucune exécution avec cet identifiant lancée par l'API IA dans l'espace.
429
rate_limited : trop d'appels avec ce jeton en une minute. Retry-After indique quand réessayer.
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·20 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, publicLimite 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.
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
{
"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.
GET/api/portal/chatbots/{key}/options
Renvoie toutes les valeurs acceptées par la mise à jour : fournisseurs et modèles d'IA autorisés par le forfait, niveaux de qualité, thèmes, dispositions, lanceurs, styles de réponse et styles de champ de saisie.
Authentification Jeton Bearer (portal)Limite de débit Aucune limite de route
Lisez-le pour construire un formulaire plutôt que de coder les listes en dur. Les choix dépendent du forfait et de l'usage ou non d'une clé fournisseur propre, et ils évoluent avec les forfaits. Les clés elles-mêmes ne sont jamais renvoyées, seulement le fait qu'une clé existe.
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.
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ôlemanage-chatbotsLimite 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://magiz.ai/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.
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ôlemanage-contentLimite 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://magiz.ai/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."
}'
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/conversations
La liste des conversations, avec les non lus et les totaux par section.
Authentification Jeton Bearer (portal)Droit du rôleview-inboxLimite de débit Aucune limite de route
Le même flux que la boîte de réception du tableau de bord et les applications agent, afin que les deux ne divergent jamais. Utilisez filter pour restreindre : all, waiting, mine, team, ai ou resolved. Jusqu'à 60 lignes, les plus urgentes d'abord.
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.
Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
403
Le compte ou l'espace de travail a été suspendu.
GET/api/portal/conversations/{conversation}
Une conversation avec sa transcription complète, et la marque comme lue.
Authentification Jeton Bearer (portal)Droit du rôleview-inboxLimite de débit Aucune limite de route
La lecture ne demande que view-inbox : un client peut donc donner à un collègue la visibilité de ses discussions sans le droit de répondre aux clients.
Paramètres
Paramètre
Type
Obligatoire
Description
conversation
uuid
Obligatoire
Chemin. L'identifiant public de la conversation, un UUID.
Répond au visiteur en tant qu'humain et reprend la conversation à l'IA.
Authentification Jeton Bearer (portal)Droit du rôlehandle-conversationsLimite de débit 60 requêtes toutes les 1 min, par utilisateur connecté
Envoyer une réponse arrête l'IA sur cette conversation et annule le compte à rebours de transfert. Passez client_id lors d'une nouvelle tentative : si le premier essai nous est bien parvenu, le message déjà enregistré est renvoyé au lieu que le client le reçoive deux fois.
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.
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/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.
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. Quand l'espace de travail a activé File d'attente, Réservations ou Clients, elle fait aussi tourner l'accueil : la file du jour, l'agenda du jour et le registre des personnes. Chaque action exécute la même logique locataire que le tableau de bord, donc le comportement est identique.
Chemin de base/api/agent·44 points de terminaison
POST/api/agent/login
Échange un e-mail et un mot de passe contre un jeton Bearer d'agent.
Authentification Aucune, publicLimite 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. Avec la connexion en deux étapes activée, le code est envoyé avec l'e-mail et le mot de passe ; un espace de travail qui l'exige ne donne aucun jeton à une personne qui ne l'a pas activée.
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.
code
string
Facultatif
Seulement si la connexion en deux étapes est activée pour ce compte : le code à 6 chiffres de l'application d'authentification, ou un code de secours, envoyé avec le même e-mail et le même mot de passe.
L'e-mail ou le mot de passe est erroné. Le texte est le même que l'adresse existe ou non.
401
La connexion en deux étapes est activée pour ce compte : two_factor vaut code_required si aucun code n'a été envoyé, wrong_code s'il ne correspond pas. Les essais de code sont limités à 6 par 5 minutes par compte et par adresse.
403
Ce compte ne peut pas traiter de conversations, ou son espace de travail est indisponible.
403
Le champ two_factor vaut setup_required : l'espace de travail exige la connexion en deux étapes de cette personne et elle n'est pas activée. Elle l'active dans son profil sur le web, puis se reconnecte.
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.
Le champ two_factor vaut setup_required : l'espace de travail exige désormais la connexion en deux étapes de cette personne et elle n'est pas activée. Le jeton est supprimé ; reconnectez-vous une fois qu'elle est activée.
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
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.
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)Droit du rôleview-inboxLimite 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.
Renvoie une conversation complète, avec sa transcription, le profil du visiteur, les étiquettes, les notes et les événements.
Authentification Jeton Bearer (agent)Droit du rôleview-inboxLimite 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.
Envoie une réponse d'agent et la délivre sur le canal utilisé par la conversation.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite 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://magiz.ai/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.
GET/api/agent/attachments/options
Ce que cet agent peut joindre : types acceptés, taille limite et nombre de fichiers par envoi.
Authentification Jeton Bearer (agent)Droit du rôleview-inboxLimite de débit Aucune limite de route
À lire au démarrage plutôt que de coder les limites en dur : un changement sur la plateforme atteint ainsi une application installée sans passer par une mise à jour du store.
Envoie de un à cinq fichiers au visiteur, avec une légende facultative.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 30 requêtes toutes les 1 min, par utilisateur connecté
Envoyer un fichier, c'est répondre : la conversation est reprise exactement comme avec une réponse texte, et le fichier part sur le canal où se trouve le visiteur. Un lot partiel renvoie 207 avec les messages envoyés et les fichiers refusés, car jeter un travail déjà abouti est pire qu'un résultat mixte.
Paramètres
Paramètre
Type
Obligatoire
Description
conversation
uuid
Obligatoire
Chemin. L'identifiant public de la conversation, un UUID.
files[]
file
Obligatoire
De un à cinq fichiers, envoyés en multipart. Tout type non accepté, ou dépassant la taille limite, est refusé fichier par fichier.
caption
string
Facultatif
Texte envoyé avec le premier fichier. Les autres portent leur nom de fichier.
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://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/attachments \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Accept: application/json" \
-F "files[]=@/path/to/replacement-label.pdf" \
-F "caption=Here is the return label." \
-F "client_id=outbox-2026-08-08-0008"
{
"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ôlehandle-conversationsLimite 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.
Renvoie les commandes Shopify et l'abonnement Stripe du visiteur pour le panneau client.
Authentification Jeton Bearer (agent)Droit du rôleview-inboxLimite 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.
Rédige une réponse pour l'agent, appuyée sur les connaissances du chatbot.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite 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://magiz.ai/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.
{
"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ôlehandle-conversationsLimite 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.
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)Droit du rôleview-inboxLimite 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.
Engage la conversation avec un visiteur en train de naviguer en lui envoyant le premier message.
Authentification Jeton Bearer (agent)Droit du rôleview-inboxLimite 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://magiz.ai/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.
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.
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.
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.
GET/api/agent/apps
Liste les onglets d'applications que cette personne peut ouvrir dans les applications agents : File d'attente, Réservations et Clients, chacun seulement tant qu'il est activé pour l'espace de travail. Les applications de santé ne sont jamais listées.
Authentification Jeton Bearer (agent)Limite de débit 60 requêtes toutes les 1 min, par utilisateur connecté
Une application est listée quand elle est activée dans Applications et que la personne a la permission que demandent ses écrans du tableau de bord. Redemandez chaque fois que l'application revient au premier plan. Un serveur sans cet endpoint répond 404 : n'affichez que la boîte de réception.
La limite de route pour cet utilisateur a été atteinte.
GET/api/agent/queue
Les files d'attente de l'espace de travail et l'accueil d'une file aujourd'hui : le numéro en cours, les personnes en attente dans l'ordre d'appel, celles qui ont manqué leur tour, les dernières sorties et les chiffres de la séance.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 120 requêtes toutes les 1 min, par utilisateur connecté
Les noms et numéros de téléphone sont réservés à l'équipe. Une personne limitée à certaines agences ne voit que les files de ces agences. Redemandez toutes les poll_seconds tant que l'écran est ouvert.
Paramètres
Paramètre
Type
Obligatoire
Description
line
integer
Facultatif
Requête. La file à afficher. Par défaut, la première file en ligne.
sitting
integer
Facultatif
Requête. La séance à afficher. Par défaut, celle en cours, sinon la suivante.
app_off : l'application est désactivée pour l'espace de travail. Un responsable peut l'activer dans Applications.
403
Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404
Aucune file, aucun ticket ou aucune séance de ce type dans cet espace de travail et les agences de la personne.
429
La limite de route pour cet utilisateur a été atteinte.
POST/api/agent/queue/lines/{line}/next
Suivant : le patient en consultation est marqué comme vu, ou comme absent avec skip, et le suivant est appelé. Avec ticket, c'est ce ticket qui est appelé.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 240 requêtes toutes les 1 min, par utilisateur connecté
Envoyez la version de la séance lue en dernier. Un appui fait sur une image plus ancienne ne change rien et répond 409 avec le code stale : deux appuis ne font jamais avancer la file deux fois.
Paramètres
Paramètre
Type
Obligatoire
Description
line
integer
Obligatoire
Chemin. L'identifiant de la file.
sitting
integer
Obligatoire
L'identifiant de la séance, depuis desk.sitting.id.
version
integer
Obligatoire
desk.sitting.version de votre dernière lecture.
skip
boolean
Facultatif
true quand le patient appelé n'est pas là.
ticket
integer
Facultatif
Un ticket en attente ou manqué à appeler à la place du suivant.
Un ticket : here (sur place, ou de retour dans la file après un tour manqué), emergency (passe ensuite), cancel, done (vu, n'appeler personne) ou skip (absent, n'appeler personne).
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 240 requêtes toutes les 1 min, par utilisateur connecté
Chaque action est inscrite dans l'historique de la file avec la personne qui a appuyé, comme à l'accueil du tableau de bord. La réponse est l'accueil de la file après l'action, sous la forme renvoyée par GET /api/agent/queue, avec ok et un message.
app_off : l'application est désactivée pour l'espace de travail. Un responsable peut l'activer dans Applications.
403
Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404
Aucune file, aucun ticket ou aucune séance de ce type dans cet espace de travail et les agences de la personne.
409
Le ticket ou la séance ne peut pas faire cette action maintenant : le code est ended, not_live, not_called, closed, full ou stopped.
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/queue/lines/{line}/walk-in
Donne un ticket à l'accueil sur la séance affichée, même quand elle est complète ou ne prend plus de tickets. Le nom et le téléphone sont facultatifs.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 60 requêtes toutes les 1 min, par utilisateur connecté
Chaque action est inscrite dans l'historique de la file avec la personne qui a appuyé, comme à l'accueil du tableau de bord. La réponse est l'accueil de la file après l'action, sous la forme renvoyée par GET /api/agent/queue, avec ok et un message.
Paramètres
Paramètre
Type
Obligatoire
Description
line
integer
Obligatoire
Chemin. L'identifiant de la file.
sitting
integer
Obligatoire
L'identifiant de la séance, depuis desk.sitting.id.
name
string
Facultatif
Facultatif. 80 caractères au plus.
phone
string
Facultatif
Facultatif. 20 caractères au plus, avec l'indicatif du pays.
La séance : mettre en pause, reprendre, arrêter les nouveaux tickets, les rouvrir ou la terminer.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 60 requêtes toutes les 1 min, par utilisateur connecté
Chaque action est inscrite dans l'historique de la file avec la personne qui a appuyé, comme à l'accueil du tableau de bord. La réponse est l'accueil de la file après l'action, sous la forme renvoyée par GET /api/agent/queue, avec ok et un message.
Paramètres
Paramètre
Type
Obligatoire
Description
line
integer
Obligatoire
Chemin. L'identifiant de la file.
sitting
integer
Obligatoire
Chemin. L'identifiant de la séance.
op
string
Obligatoire
pause, resume, stop, open ou end. Terminer compte le patient en consultation comme vu et met fin à tous les tickets encore en attente.
app_off : l'application est désactivée pour l'espace de travail. Un responsable peut l'activer dans Applications.
403
Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404
Aucune file, aucun ticket ou aucune séance de ce type dans cet espace de travail et les agences de la personne.
409
Le ticket ou la séance ne peut pas faire cette action maintenant : le code est ended, not_live, not_called, closed, full ou stopped.
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/bookings
L'agenda d'une journée à l'heure de l'espace de travail : les réservations qui occupent un créneau ce jour-là, avec les coordonnées et les changements que chacune permet maintenant.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 120 requêtes toutes les 1 min, par utilisateur connecté
Les réservations annulées ou refusées libèrent leur créneau et sont omises. Les réponses aux questions et les notes internes ne sont jamais renvoyées. Une personne limitée à certaines agences ne voit que leurs réservations.
Paramètres
Paramètre
Type
Obligatoire
Description
date
string
Facultatif
Requête. AAAA-MM-JJ dans le fuseau horaire de l'espace de travail. Par défaut, aujourd'hui.
app_off : l'application est désactivée pour l'espace de travail. Un responsable peut l'activer dans Applications.
403
Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
429
La limite de route pour cet utilisateur a été atteinte.
POST/api/agent/bookings/{booking}/status
Change une réservation comme l'équipe le fait dans le tableau de bord : confirmer ou refuser une réservation en attente, annuler une réservation confirmée, marquer une réservation commencée comme faite ou comme absence.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 60 requêtes toutes les 1 min, par utilisateur connecté
Le changement est inscrit au journal d'activité, le client reçoit le même message que depuis le tableau de bord, et les workflows et webhooks reçoivent l'événement de réservation.
Paramètres
Paramètre
Type
Obligatoire
Description
booking
integer
Obligatoire
Chemin. L'identifiant de la réservation.
action
string
Obligatoire
confirm, decline, cancel, completed ou no_show. La liste actions d'une réservation indique lesquels s'appliquent maintenant.
reason
string
Facultatif
Facultatif, avec decline ou cancel. 250 caractères au plus.
scope
string
Facultatif
later, avec cancel : cette réservation et les suivantes de sa série.
app_off : l'application est désactivée pour l'espace de travail. Un responsable peut l'activer dans Applications.
403
Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404
Aucune réservation de ce type dans cet espace de travail et les agences de la personne.
409
La réservation ne peut pas faire ce changement maintenant : le code est booking_not_pending, booking_not_active, booking_not_started ou booking_too_late.
422
Un champ a échoué à la validation. L'objet errors le nomme.
429
La limite de route pour cet utilisateur a été atteinte.
501
not_available : ce serveur ne peut pas changer de réservation depuis les applications agents.
GET/api/agent/customers
Trouve des personnes par nom, téléphone ou e-mail, les plus récemment modifiées d'abord. Sans q, les dernières personnes.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 60 requêtes toutes les 1 min, par utilisateur connecté
Paramètres
Paramètre
Type
Obligatoire
Description
q
string
Facultatif
Requête. Un nom, un téléphone ou un e-mail. Une recherche par téléphone ignore les espaces et l'indicatif.
app_off : l'application est désactivée pour l'espace de travail. Un responsable peut l'activer dans Applications.
403
Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
429
La limite de route pour cet utilisateur a été atteinte.
GET/api/agent/customers/{person}
Un profil court : coordonnées, réservations à venir et récentes, et le nombre de factures ouvertes quand Factures est activé.
Authentification Jeton Bearer (agent)Droit du rôlehandle-conversationsLimite de débit 60 requêtes toutes les 1 min, par utilisateur connecté
La note de la personne n'est jamais renvoyée. Une fiche fusionnée répond avec celle qu'elle est devenue. open_invoices vaut null quand Factures est désactivé.
app_off : l'application est désactivée pour l'espace de travail. Un responsable peut l'activer dans Applications.
403
Le jeton est valide, mais le rôle de l'utilisateur n'accorde pas cette action.
404
Aucune personne de ce type dans cet espace de travail.
429
La limite de route pour cet utilisateur a été atteinte.
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, publicLimite 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.
{
"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://magiz.ai",
"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, publicLimite 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. Le champ identity indique ce que cette requête a prouvé sur la personne qui écrit. Son state vaut verified, staff_view, expired, refused, client_area_no_client, staff_session, no_account, account_closed, module_error, not_configured, sign_in_page, signed_out ou absent. Il ne contient first_name que lorsque le jeton d'identité de cette requête a été vérifié pour un client, jamais en vue équipe.
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. Un jeton dont sub ou external_id vaut "0" est refusé. Une conversation connectée continue sans jeton pendant 15 minutes après le dernier jeton vérifié. Ensuite, elle est mise de côté et une nouvelle conversation commence, et le prochain jeton valide de la même personne la fait revenir dans les 24 heures.
signed_out
boolean
Facultatif
Envoyez true quand votre page sait que personne n'est connecté. Si la conversation appartient à une personne connectée plus tôt, elle est fermée et une nouvelle commence, pour que la personne suivante sur un ordinateur partagé ne la voie jamais.
identity_state
object
Facultatif
La raison pour laquelle la page n'a pas de jeton d'identité, en codes uniquement : {"v":1,"status":"client|staff|none","reason":"..."}. Le motif est signed_out, staff, staff_view, no_account, account_closed, module_error ou not_configured. Il sert à formuler les réponses et ne donne jamais accès à quoi que ce soit. Tout ce qui sort de ce format est ignoré.
{
"conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
"status": "bot",
"handoff_state": "bot_active",
"wait_remaining": null,
"identity": { "state": "absent" },
"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, publicLimite 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. L'événement meta porte aussi identity, le même objet que renvoie boot.
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. Un jeton dont sub ou external_id vaut "0" est refusé. Une conversation connectée continue sans jeton pendant 15 minutes après le dernier jeton vérifié. Ensuite, elle est mise de côté et une nouvelle conversation commence, et le prochain jeton valide de la même personne la fait revenir dans les 24 heures.
signed_out
boolean
Facultatif
Envoyez true quand votre page sait que personne n'est connecté. Si la conversation appartient à une personne connectée plus tôt, elle est fermée et une nouvelle commence, pour que la personne suivante sur un ordinateur partagé ne la voie jamais.
identity_state
object
Facultatif
La raison pour laquelle la page n'a pas de jeton d'identité, en codes uniquement : {"v":1,"status":"client|staff|none","reason":"..."}. Le motif est signed_out, staff, staff_view, no_account, account_closed, module_error ou not_configured. Il sert à formuler les réponses et ne donne jamais accès à quoi que ce soit. Tout ce qui sort de ce format est ignoré.
Requête
curl -N -X POST https://magiz.ai/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","identity":{"state":"absent"}}
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, publicLimite 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é.
Interroge une conversation pour les nouveaux messages, y compris les réponses d'un agent humain.
Authentification Aucune, publicLimite 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é. Une conversation connectée répond {"reauth": true, "messages": []} dès que son dernier jeton vérifié date de plus de 15 minutes. Rappelez boot avec le jeton d'identité de la page pour continuer.
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.
{
"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.
Enregistre un pouce en haut ou en bas sur une réponse de l'IA.
Authentification Aucune, publicLimite 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.
Enregistre une note de satisfaction pour toute la conversation.
Authentification Aucune, publicLimite 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://magiz.ai/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.
GET
/widget/{key}/attachments/{attachment}
Diffuse une pièce jointe au visiteur propriétaire de la conversation. L'adresse est émise par le widget et vérifiée contre ce visiteur.
POST
/widget/{key}/chat/reveal/{token}
Échange un jeton à usage unique contre une information demandée par le visiteur et que rien ne doit conserver, comme son mot de passe d'hébergement. Seul le bouton du widget l'appelle. Un jeton ne sert qu'une fois, pendant 3 minutes, dans la conversation connectée pour laquelle il a été créé et uniquement pour le visiteur à qui elle appartient. Les identifiants ne sont affichés que pour une installation WHMCS dont le module est en version 1.6.0 ou ultérieure. Toute autre requête est refusée (404, 410 ou 422) et ne reçoit rien.
POST
/widget/{key}/chat/verification
Indique si un code de confirmation envoyé par e-mail attend dans la conversation du visiteur, l'adresse masquée à laquelle il est parti et le nombre d'essais restants. Seule la zone de code du widget l'appelle, pour le visiteur à qui appartient la conversation. Ne renvoie jamais le code.
POST
/widget/{key}/chat/verification/{ref}/code
Vérifie un code saisi dans la zone de code du widget par rapport au code envoyé par e-mail pour une modification. Cinq essais par demande, puis la demande est fermée. Un code correct n'est ni conservé ni transmis : le widget envoie ensuite un simple message, qui déclenche la modification par le tour de chat habituel.
POST
/widget/{key}/chat/verification/{ref}/resend
Envoie un nouveau code par le même canal e-mail, qui remplace le précédent. Trois fois au plus par demande, à trente secondes d'intervalle, et dans la limite horaire du marchand. Ne renvoie que l'adresse masquée.
POST
/widget/{key}/chat/pay/{token}
Le bouton Payer sous la première commande d'un nouveau client (module WHMCS 1.8.0). Échange un jeton contre la connexion unique de WHMCS au compte que cette conversation a ouvert, sur sa facture, créée à ce moment-là. Seul le bouton du widget l'appelle, depuis la conversation pour laquelle le jeton a été créé et pour le visiteur à qui elle appartient, pendant deux heures. Toute autre requête est refusée (404, 410 ou 422) et ne reçoit rien.
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.