TALKR

Restricted Access

This page is restricted to the TALKR team.

📡 API Reference

Chatbot API TALKR.ai v4.2

Integrate a TALKR conversational chatbot on your website, mobile app, or telephony server. One endpoint, two channels: web and telephony.

Get started → Test the API

Overview

The TALKR Chatbot API lets you control a conversational agent via HTTP requests. It is used by both the web widget and telephony servers (SIP/VoIP). The principle is simple:

  1. You send a POST to initiate the conversation
  2. The bot returns a welcome message + a session identifier
  3. You send user messages with the session and tracking
  4. The bot processes the intent and returns its response

Base URL

🔒 URL provided on request

The API base URL is provided when your TALKR account is created. Contact us to get your access credentials (company, bot_id, endpoint).

URL parameters

VariableDescription
{company} Your TALKR workspace name (provided at registration)
{bot_id} Numeric identifier of your bot (visible in the platform)
{channel} Communication channel: web or telephony

Authentication

The API is open (no API key required for conversational calls). Identification is done via the company + bot_id pair in the URL.

For the web channel, add the header:

X-Talkr-Query: 1

Quickstart — 3 minutes to integrate

Here's how to start a conversation in 2 API calls:

Step 1 — Initiate the conversation

POST Endpoint provided at registration
curl # First call: get the welcome message + session curl -X POST "{YOUR_API_ENDPOINT}" \ -H "Content-Type: application/json" \ -H "X-Talkr-Query: 1" \ -d '{}'

You receive a JSON with:

  • session — unique conversation identifier (keep this)
  • data.messages[0].content — bot welcome message
  • data.responses[0].tracking — current block identifier

Step 2 — Send a user message

curl # Second call: send the user's response curl -X POST "{YOUR_API_ENDPOINT}" \ -H "Content-Type: application/json" \ -H "X-Talkr-Query: 1" \ -d '{ "message": "how does talkr work?", "session": "YOUR_SESSION_ID", "tracking": "TRACKING_FROM_PREVIOUS_STEP", "variables": { "userresponse": "how does talkr work?" } }'

The bot analyzes the intent and returns its response in variables.bot_answer and data.messages.

Conversation flow

Each conversation follows this cycle:

1. Init (empty POST) → Welcome + session → 2. User message → Bot response → 3. Repeat

Key fields to send on each turn

FieldSourceRole
session Response from step 1 Identifies the current conversation — keep throughout the exchange
tracking data.responses[0].tracking Indicates the conversation tree block. Tells the bot where it is
variables.userresponse Text typed by the user Contains the user's response for NLU/AI processing

Web channel (chat)

Endpoint for web chat integrations (widget, website, mobile app).

POST Endpoint provided at registration

Required headers

HeaderValueRequired
Content-Type application/json required
X-Talkr-Query 1 required

Telephony channel (SIP/VoIP)

Endpoint for telephony integrations (SIP, VoIP, IVR). Same request/response format as the web channel, with additional data for text-to-speech (TTS) and speech recognition (STT).

POST Endpoint provided at registration

Additional response data

FieldDescription
data.speech_synthesis TTS configuration (vendor, voice, ElevenLabs/Google/Azure options)
data.speech_recognizer STT configuration (vendor, language, recognition timeouts)
data.hangup_no_response Auto hang up if no response (0 or 1)
data.retries Number of retry prompts before abandoning

Request parameters (JSON body)

Initial call (start a conversation)

JSON { } // empty body or {}

Subsequent calls (send a message)

ParameterTypeRequiredDescription
message string required User message text
session string required Session identifier returned by the initial call
tracking string required Conversation block identifier (data.responses[0].tracking)
variables object required Object containing userresponse (the user's text)
variables.userresponse string required User's response — used by the NLU/AI engine to process intent
currentUrl string optional URL of the page where the user is located (context)

Response structure

200 Success — the response contains bot data.

JSON { "session": "abc123...", "code": 200, "name": "Bot name", "language": { "name": "French", "slug": "FR" }, "variables": { "bot_answer": "Final bot response", // main message "model": "gpt-4o", "jour": "friday", "heure": "14:30", "horaire": "horairein" // ... other bot variables }, "data": { "messages": [ // displayed messages (may be intermediate) { "type": "text", "content": "Please wait..." } ], "responses": [ // retry blocks if no response { "type": "custom", "content": "Sorry, what did you say?", "tracking": "175173..." // send this back on next call } ], "object_id": "175173...", "has_background_text": 1, // 1 if bot processes in background "background_content": "ok" } }

Key response fields

FieldDescription
session Session identifier to keep for the entire conversation
variables.bot_answer Final bot response (after NLU/AI processing). This is the main message to display
data.messages Messages displayed by the bot. May be an intermediate message ("please wait...") before the final response
data.responses[0].tracking Current conversation block identifier. Send this back in the next call
data.has_background_text 1 if the bot performs background processing. Display data.messages as a waiting message, then variables.bot_answer as the final response

Code examples

JavaScript (fetch) const API = '{YOUR_API_ENDPOINT}'; const HEADERS = { 'Content-Type': 'application/json', 'X-Talkr-Query': '1' }; // Step 1: start the 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); // Step 2: send a message const reply = await fetch(API, { method: 'POST', headers: HEADERS, body: JSON.stringify({ message: 'how does talkr work?', session, tracking, variables: { userresponse: 'how does talkr work?' } }) }); const d2 = await reply.json(); console.log('Bot:', d2.variables.bot_answer);
Python (requests) import requests API = "{YOUR_API_ENDPOINT}" HEADERS = { "Content-Type": "application/json", "X-Talkr-Query": "1" } # Step 1: start the 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']}") # Step 2: send a message r2 = requests.post(API, json={ "message": "how does talkr work?", "session": session, "tracking": tracking, "variables": { "userresponse": "how does talkr work?" } }, headers=HEADERS) d2 = r2.json() print(f"Bot: {d2['variables']['bot_answer']}")
cURL (terminal) # Step 1: start the conversation curl -X POST "{YOUR_API_ENDPOINT}" \ -H "Content-Type: application/json" \ -H "X-Talkr-Query: 1" \ -d '{}' # Step 2: send a message (replace SESSION and TRACKING) curl -X POST "{YOUR_API_ENDPOINT}" \ -H "Content-Type: application/json" \ -H "X-Talkr-Query: 1" \ -d '{ "message": "how does talkr work?", "session": "SESSION_ID", "tracking": "TRACKING_ID", "variables": { "userresponse": "how does talkr work?" } }'
PHP <?php $api = "{YOUR_API_ENDPOINT}"; 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); } // Step 1: start $data = callTalkr($api); $session = $data['session']; $tracking = $data['data']['responses'][0]['tracking']; echo "Bot: " . $data['variables']['bot_answer'] . "\n"; // Step 2: send a message $d2 = callTalkr($api, [ 'message' => 'how does talkr work?', 'session' => $session, 'tracking' => $tracking, 'variables' => [ 'userresponse' => 'how does talkr work?' ] ]); echo "Bot: " . $d2['variables']['bot_answer'] . "\n";

Test the API

Try it live — send a message to the bot

Error codes

CodeMeaningAction
200 Success Process the response normally
400 Invalid request Check JSON format and required fields
404 Bot not found Check company and bot_id in the URL
500 Server error Retry after a few seconds

The variables.error field in the response may contain details about internal bot errors (e.g., missing variable in the conversation tree).

FAQ

What's the difference between the web channel and the telephony channel?

The request format and conversation flow are identical. The telephony channel response additionally includes TTS (text-to-speech) and STT (speech recognition) configurations for SIP/VoIP servers.

How long does a session last?

A session stays active as long as there are exchanges. After a configurable period of inactivity (per bot), the session expires and a new initial call is needed.

The bot shows "please wait" then the real answer — how to handle this?

When data.has_background_text = 1, the bot performs AI processing in the background. Display data.messages[0].content (waiting message) first, then variables.bot_answer (final response) with a slight delay between the two.

Do I need an API key?

No, the conversational API is open. Identification is done via the company/bot_id pair in the URL. For bot management (creation, configuration), a separate admin API with authentication is available.

Can I use this API from a Node.js, Python, PHP backend...?

Yes, the API is a simple REST endpoint (POST + JSON). It works with any language capable of making HTTP requests. See examples in the "Code examples" section.