📡 API Reference

API Chatbot TALKR.ai v4.2

Intégrez un chatbot conversationnel TALKR sur votre site web, application mobile ou serveur téléphonique. Un seul endpoint, deux canaux : web et téléphonie.

Commencer → Tester l'API

Vue d'ensemble

L'API Chatbot TALKR permet de piloter un agent conversationnel par requêtes HTTP. Elle est utilisée aussi bien par le widget web que par les serveurs de téléphonie (SIP/VoIP). Le principe est simple :

Vous envoyez un POST pour initier la conversation
Le bot retourne un message d'accueil + un identifiant de session
Vous renvoyez les messages de l'utilisateur avec la session et le tracking
Le bot traite l'intention et retourne sa réponse

URL de base

🔒 URL fournie sur demande

L'URL de base de l'API est communiquée lors de la création de votre compte TALKR. Contactez-nous pour obtenir vos identifiants d'accès (company, bot_id, endpoint).

Paramètres de l'URL

Variable	Description
{company}	Nom de votre espace TALKR (fourni à l'inscription)
{bot_id}	Identifiant numérique de votre bot (visible dans la plateforme)
{channel}	Canal de communication : `web` ou `telephony`

Authentification

L'API est ouverte (pas de clé API requise pour les appels conversationnels). L'identification se fait via le couple company + bot_id dans l'URL.

Pour le canal web, ajoutez le header :

X-Talkr-Query: 1

Quickstart — 3 minutes pour intégrer

Voici comment lancer une conversation en 2 appels :

Etape 1 — Initier la conversation

POST Endpoint fourni à l'inscription

                                curl
# Premier appel : récupérer le message d'accueil + session
curl -X POST "{VOTRE_ENDPOINT_API}" \
  -H "Content-Type: application/json" \
  -H "X-Talkr-Query: 1" \
  -d '{}'
                            

Vous recevez un JSON avec :

session — identifiant unique de la conversation (a conserver)
data.messages[0].content — message d'accueil du bot
data.responses[0].tracking — identifiant du bloc courant

Etape 2 — Envoyer un message utilisateur

                                curl
# Deuxième appel : envoyer la réponse de l'utilisateur
curl -X POST "{VOTRE_ENDPOINT_API}" \
  -H "Content-Type: application/json" \
  -H "X-Talkr-Query: 1" \
  -d '{
    "message": "comment fonctionne talkr ?",
    "session": "VOTRE_SESSION_ID",
    "tracking": "TRACKING_DU_STEP_PRECEDENT",
    "variables": {
      "userresponse": "comment fonctionne talkr ?"
    }
  }'
                            

Le bot analyse l'intention et retourne sa réponse dans variables.bot_answer et data.messages.

Flux conversationnel

Chaque conversation suit ce cycle :

1. Init (POST vide) → Accueil + session → 2. Message user → Réponse bot → 3. Répéter

Champs importants a transmettre a chaque tour

Champ	Provenance	Role
session	Reponse du step 1	Identifie la conversation en cours — a conserver tout au long de l'échange
tracking	`data.responses[0].tracking`	Indique le bloc de l'arbre conversationnel. Permet au bot de savoir ou il en est
variables.userresponse	Texte saisi par l'utilisateur	Contient la réponse de l'utilisateur pour le traitement NLU/IA

Canal Web (chat)

Endpoint pour les intégrations chat web (widget, site, app mobile).

POST Endpoint fourni à l'inscription

Headers requis

Header	Valeur	Obligatoire
Content-Type	`application/json`	requis
X-Talkr-Query	`1`	requis

Canal Téléphonie (SIP/VoIP)

Endpoint pour les intégrations téléphonie (SIP, VoIP, IVR). Meme format de requête/réponse que le canal web, avec des données supplémentaires pour la synthèse vocale (TTS) et la reconnaissance vocale (STT).

POST Endpoint fourni à l'inscription

Données supplémentaires en réponse

Champ	Description
data.speech_synthesis	Configuration TTS (vendor, voix, options ElevenLabs/Google/Azure)
data.speech_recognizer	Configuration STT (vendor, langue, timeouts de reconnaissance)
data.hangup_no_response	Raccrocher automatiquement si pas de réponse (0 ou 1)
data.retries	Nombre de relances avant abandon

Paramètres de requête (body JSON)

Appel initial (démarrer une conversation)

                                JSON
{ }   // body vide ou {}
                            

Appels suivants (envoyer un message)

Paramètre	Type	Requis	Description
message	string	requis	Texte du message de l'utilisateur
session	string	requis	Identifiant de session retourné par l'appel initial
tracking	string	requis	Identifiant du bloc conversationnel (`data.responses[0].tracking`)
variables	object	requis	Objet contenant `userresponse` (le texte de l'utilisateur)
variables.userresponse	string	requis	Réponse de l'utilisateur — utilisée par le moteur NLU/IA pour traiter l'intention
currentUrl	string	optionnel	URL de la page ou se trouve l'utilisateur (contexte)

Structure de la réponse

200 Succès — la réponse contient les données du bot.

                                JSON
{
  "session": "abc123...",
  "code": 200,
  "name": "Nom du bot",
  "language": { "name": "French", "slug": "FR" },

  "variables": {
    "bot_answer": "Réponse finale du bot",    // ← message principal
    "model": "gpt-4o",
    "jour": "vendredi",
    "heure": "14:30",
    "horaire": "horairein"
    // ... autres variables du bot
  },

  "data": {
    "messages": [                          // ← messages affichés (peut etre intermédiaire)
      { "type": "text", "content": "Attendez un moment..." }
    ],
    "responses": [                         // ← blocs de relance si pas de réponse
      {
        "type": "custom",
        "content": "Pardon, que disiez-vous ?",
        "tracking": "175173..."        // ← a renvoyer au prochain appel
      }
    ],
    "object_id": "175173...",
    "has_background_text": 1,            // ← 1 si le bot traite en arrière-plan
    "background_content": "d'accord"
  }
}
                            

Champs importants de la réponse

Champ	Description
session	Identifiant de session a conserver pour toute la conversation
variables.bot_answer	Réponse finale du bot (apres traitement NLU/IA). C'est le message principal a afficher
data.messages	Messages affichés par le bot. Peut etre un message intermédiaire ("patientez...") avant la réponse finale
data.responses[0].tracking	Identifiant du bloc conversationnel courant. A renvoyer dans le prochain appel
data.has_background_text	`1` si le bot effectue un traitement en arriere-plan. Afficher `data.messages` comme message d'attente, puis `variables.bot_answer` comme réponse finale

Exemples de code

                                    JavaScript (fetch)
const API = '{VOTRE_ENDPOINT_API}';
const HEADERS = {
  'Content-Type': 'application/json',
  'X-Talkr-Query': '1'
};

// Etape 1 : démarrer la conversation
const init = await fetch(API, {
  method: 'POST',
  headers: HEADERS,
  body: JSON.stringify({})
});
const data = await init.json();

const session  = data.session;
const tracking = data.data.responses[0].tracking;
console.log('Bot:', data.variables.bot_answer);

// Etape 2 : envoyer un message
const reply = await fetch(API, {
  method: 'POST',
  headers: HEADERS,
  body: JSON.stringify({
    message: 'comment fonctionne talkr ?',
    session,
    tracking,
    variables: { userresponse: 'comment fonctionne talkr ?' }
  })
});
const d2 = await reply.json();
console.log('Bot:', d2.variables.bot_answer);
                                

                                    Python (requests)
import requests

API = "{VOTRE_ENDPOINT_API}"
HEADERS = {
    "Content-Type": "application/json",
    "X-Talkr-Query": "1"
}

# Etape 1 : démarrer la conversation
r1 = requests.post(API, json={}, headers=HEADERS)
data = r1.json()

session  = data["session"]
tracking = data["data"]["responses"][0]["tracking"]
print(f"Bot: {data['variables']['bot_answer']}")

# Etape 2 : envoyer un message
r2 = requests.post(API, json={
    "message": "comment fonctionne talkr ?",
    "session": session,
    "tracking": tracking,
    "variables": {
        "userresponse": "comment fonctionne talkr ?"
    }
}, headers=HEADERS)
d2 = r2.json()
print(f"Bot: {d2['variables']['bot_answer']}")
                                

                                    cURL (terminal)
# Etape 1 : démarrer la conversation
curl -X POST "{VOTRE_ENDPOINT_API}" \
  -H "Content-Type: application/json" \
  -H "X-Talkr-Query: 1" \
  -d '{}'

# Etape 2 : envoyer un message (remplacer SESSION et TRACKING)
curl -X POST "{VOTRE_ENDPOINT_API}" \
  -H "Content-Type: application/json" \
  -H "X-Talkr-Query: 1" \
  -d '{
    "message": "comment fonctionne talkr ?",
    "session": "SESSION_ID",
    "tracking": "TRACKING_ID",
    "variables": {
      "userresponse": "comment fonctionne talkr ?"
    }
  }'
                                

                                    PHP
<?php
$api = "{VOTRE_ENDPOINT_API}";

function callTalkr($api, $body = []) {
    $ch = curl_init($api);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-Talkr-Query: 1'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Etape 1 : démarrer
$data = callTalkr($api);
$session  = $data['session'];
$tracking = $data['data']['responses'][0]['tracking'];
echo "Bot: " . $data['variables']['bot_answer'] . "\n";

// Etape 2 : envoyer un message
$d2 = callTalkr($api, [
    'message'  => 'comment fonctionne talkr ?',
    'session'  => $session,
    'tracking' => $tracking,
    'variables' => [
        'userresponse' => 'comment fonctionne talkr ?'
    ]
]);
echo "Bot: " . $d2['variables']['bot_answer'] . "\n";
                                

Tester l'API

Essayez en direct — envoyez un message au bot

Endpoint Votre message

Codes d'erreur

Code	Signification	Action
200	Succès	Traiter la réponse normalement
400	Requête invalide	Vérifier le format JSON et les champs requis
404	Bot non trouvé	Vérifier company et bot_id dans l'URL
500	Erreur serveur	Réessayer apres quelques secondes

Le champ variables.error dans la réponse peut contenir des détails sur les erreurs internes du bot (ex: variable manquante dans l'arbre conversationnel).

FAQ

Quelle est la différence entre le canal web et le canal téléphonie ?

Le format de requête et le flux conversationnel sont identiques. La réponse du canal téléphonie inclut en plus les configurations TTS (synthèse vocale) et STT (reconnaissance vocale) pour les serveurs SIP/VoIP.

Combien de temps dure une session ?

Une session reste active tant qu'il y a des échanges. Apres un certain temps d'inactivité (configurable par bot), la session expire et un nouvel appel initial est nécessaire.

Le bot affiche "patientez" puis la vraie réponse — comment gérer ?

Quand data.has_background_text = 1, le bot effectue un traitement IA en arriere-plan. Affichez d'abord data.messages[0].content (message d'attente), puis variables.bot_answer (réponse finale) avec un léger délai entre les deux.

Ai-je besoin d'une clé API ?

Non, l'API conversationnelle est ouverte. L'identification se fait via le couple company/bot_id dans l'URL. Pour la gestion des bots (création, configuration), une API d'administration avec authentification est disponible séparément.

Puis-je utiliser cette API depuis un backend Node.js, Python, PHP... ?

Oui, l'API est un simple endpoint REST (POST + JSON). Elle fonctionne avec n'importe quel langage capable de faire des requêtes HTTP. Voir les exemples dans la section "Exemples de code".

Accès restreint

API Chatbot TALKR.ai v4.2

Vue d'ensemble

URL de base

Paramètres de l'URL

Authentification

Quickstart — 3 minutes pour intégrer

Etape 1 — Initier la conversation

Etape 2 — Envoyer un message utilisateur

Flux conversationnel

Champs importants a transmettre a chaque tour

Canal Web (chat)

Headers requis

Canal Téléphonie (SIP/VoIP)

Données supplémentaires en réponse

Paramètres de requête (body JSON)

Appel initial (démarrer une conversation)

Appels suivants (envoyer un message)

Structure de la réponse

Champs importants de la réponse

Exemples de code

Tester l'API

Codes d'erreur

FAQ