Aller au contenu
Orkiva

Agents commerciaux

API serveur

Utilisez un agent depuis votre propre application (site sur mesure, application mobile, outil interne) : votre serveur crée des conversations et envoie les messages, l’agent répond.

Principe

  • Adresse de l’API : https://api.getorkiva.com.
  • Authentification par token serveur okv_…, lié à un seul agent, à envoyer dans l’en-tête Authorization: Bearer okv_….
  • Le token reste sur votre serveur : ne l’intégrez jamais dans une page web ou une application mobile.
  • Un token n’a jamais accès aux prospects, aux documents ni à vos clés d’IA.

Créer un token

  1. 1

    Ouvrez Intégrations

    Menu Intégrations, choisissez l’agent, puis Nouveau token.

  2. 2

    Choisissez libellé, durée et droits

    Durée : 1, 7, 30 ou 90 jours. Droits : conversations:write (créer des conversations et envoyer des messages) et/ou conversations:read (relire une conversation).

  3. 3

    Copiez-le immédiatement

    Le token n’est affiché qu’une seule fois. La page indique ensuite sa date de création, d’expiration et de dernière utilisation.

Token compromis ?

Révoquez-le depuis Intégrations : il est refusé immédiatement. Créez-en un nouveau pour vos serveurs.

Créer une conversation

L’identifiant public de l’agent (agt_…) figure dans sa fiche et dans Intégrations.

bash
curl -X POST https://api.getorkiva.com/v1/agents/agt_VOTRE_AGENT/conversations \
  -H "Authorization: Bearer okv_VOTRE_TOKEN"

# Réponse
{ "conversationId": "0192f3a4-…" }

Envoyer un message

Générez un clientMessageId (UUID) par message : si vous renvoyez le même identifiant (coupure réseau…), Orkiva renvoie le message déjà enregistré, sans seconde réponse.

bash
curl -X POST https://api.getorkiva.com/v1/conversations/0192f3a4-…/messages \
  -H "Authorization: Bearer okv_VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientMessageId": "6f1c2b9e-8d4a-4f3e-9b1a-2c7d5e8f0a13",
    "content": "Bonjour, quels sont vos délais de livraison ?"
  }'

# Réponse
{ "message": { … }, "reply": { "role": "ASSISTANT", "content": "…" } }

Réponse progressive (streaming)

Ajoutez Accept: text/event-stream pour recevoir la réponse au fil de l’eau (Server-Sent Events) :

Événements
event: message   data: {"message": {…}}          // votre message, enregistré
event: delta     data: {"text": "Nos délais "}   // morceaux de la réponse
event: delta     data: {"text": "sont de…"}
event: done      data: {"reply": {…}}            // réponse complète
event: error     data: {"code": "PROVIDER_ERROR", "message": "…", "handoff": true}

Relire une conversation

bash
curl https://api.getorkiva.com/v1/conversations/0192f3a4-… \
  -H "Authorization: Bearer okv_VOTRE_TOKEN"   # droit conversations:read

Erreurs

Toutes les erreurs ont la même forme :

json
{
  "statusCode": 422,
  "code": "AGENT_NOT_PUBLISHED",
  "message": "Message lisible (en français)",
  "details": null,
  "requestId": "01J…"
}
Code HTTPSignification
400Requête invalide (le détail des champs est dans details).
401Token absent, invalide, expiré (TOKEN_EXPIRED) ou révoqué (TOKEN_REVOKED).
403Droit manquant pour cette opération.
404Agent ou conversation introuvable (y compris s’il appartient à une autre entreprise).
409Une réponse est déjà en cours dans cette conversation (IDEMPOTENCY_CONFLICT) : envoyez les messages un par un.
422Règle métier : agent non publié, limite de l’offre atteinte (QUOTA_EXCEEDED)…
429Trop de requêtes : réessayez après le délai de l’en-tête Retry-After.
5xxErreur temporaire, par exemple du fournisseur d’IA (PROVIDER_ERROR) : réessayez.

Limites

  • Un message : 4 000 caractères au maximum.
  • Débit : 60 créations de conversation et 20 messages par minute ; au-delà, réponse 429.
  • Les messages comptent dans le quota mensuel de votre offre (page Consommation).