Consuming Text & Voice Agents in External Applications
Langoedge Team4 min read
Integration Overview
Langoedge allows developers to invoke and interact with Text Agents and Voice Agents programmatically from external applications (such as websites, mobile applications, CRMs, or backend workers).
To authenticate your external API requests on the main API gateway, you must supply both of the following headers in all API calls:
x-langoedge-secret: Your secure API key/secret.x-langoedge-user-id: Your unique Langoedge user ID.
1. Invoking Text Agents (REST API)
To invoke a text agent execution and retrieve its state output in a single HTTP request, call the external execution endpoint.
Endpoint Definition
POST /graph-executions/invoke-from-external-app HTTP/1.1
Host: api.langoedge.com
x-langoedge-secret: YOUR_SECRET_KEY
x-langoedge-user-id: YOUR_USER_ID
Content-Type: application/x-www-form-urlencoded
Request Parameters (Form Data)
This endpoint expects request parameters encoded as Form fields (application/x-www-form-urlencoded):
| Parameter | Type | Required | Description |
|---|---|---|---|
graph_config_id |
string |
Yes | The unique ID of the text graph configuration you want to run. |
user_input |
string |
Yes | The user prompt or message text payload to pass to the agent. |
thread_id |
string |
No | A persistent thread identifier to preserve conversation memory (defaults to "1"). |
Example JavaScript Request
const params = new URLSearchParams();
params.append('graph_config_id', 'graph_cfg_987654');
params.append('user_input', 'Check shipping status for order 99281');
params.append('thread_id', 'thread_user_abc123');
fetch('https://api.langoedge.com/graph-executions/invoke-from-external-app', {
method: 'POST',
headers: {
'x-langoedge-secret': 'lg_sec_your_secret_here',
'x-langoedge-user-id': 'usr_user_id_here',
'Content-Type': 'application/x-www-form-urlencoded'
},
body: params
})
.then(res => res.text())
.then(responseText => {
console.log("Agent response:", responseText);
});
2. Invoking Voice Agents (Outbound Dialing)
To programmatically trigger a voice agent to call an external phone number (e.g. for customer follow-up calls or automated booking reminders), invoke our dialer endpoint.
Endpoint Definition
POST /voice-graphs/{voice_graph_id}/call HTTP/1.1
Host: api.langoedge.com
x-langoedge-secret: YOUR_SECRET_KEY
x-langoedge-user-id: YOUR_USER_ID
Content-Type: application/json
Request Payload (JSON Body)
Unlike the text API, the voice dialing endpoint expects a JSON payload:
{
"phone_number": "+15550192834",
"metadata": {
"customer_name": "John Doe",
"appointment_time": "2026-06-11T14:00:00Z"
}
}
phone_number: (Required) The recipient's phone number, formatted in the international E.164 standard.metadata: (Optional) Key-value pairs to pre-populate variables on the agent's shared state notepad before the conversation starts.
3. Retrieving Voice Session History
You can programmatically fetch call logs, transcripts, and session details for all interactions handled by a specific voice agent.
Endpoint Definition
GET /voice-graphs/{voice_graph_id}/chat-history/external HTTP/1.1
Host: api.langoedge.com
x-langoedge-secret: YOUR_SECRET_KEY
x-langoedge-user-id: YOUR_USER_ID
Response Format
Returns an array of session records. Each record contains detailed metrics, timestamps, and a conversation transcript array. Example response:
[
{
"session_id": "sess_abc123",
"voice_graph_id": "6a1bfe2dc9e17ba91f9ed664",
"started_at": "2026-06-10T14:22:00Z",
"ended_at": "2026-06-10T14:27:43Z",
"duration_seconds": 343,
"call_status": "completed",
"transcript": [
{ "role": "agent", "content": "Hello, how can I help you today?", "timestamp": "2026-06-10T14:22:05Z" },
{ "role": "user", "content": "I need to reschedule my appointment.", "timestamp": "2026-06-10T14:22:12Z" }
]
}
]
Dynamic Voice Stream Routing
To ensure conversational voice agents feel natural and lag-free, WebRTC client connections are routed dynamically at the LiveKit Cloud DNS layer.
- Unified API Base URL:
https://api.langoedge.com(REST API requests are served from our primary deployment region). - Global Voice Mesh: Langoedge dynamically connects WebRTC clients and SIP calls to the nearest regional media server (with servers located in US East, Western Europe, and Sydney) to ensure human-level conversation with low latency.
Developer Integration Checklist
1
Retrieve API Secrets, User ID, and Graph IDs
Go to Langoedge Console -> Settings -> Profile to copy your User ID, and to Settings -> API Keys to generate your secret. To find a **`graph_config_id`**, open the target Text Graph in the dashboard — the ID appears in the browser URL (e.g. `app.langoedge.com/graphs/graph_cfg_987654`) and in the graph's Settings panel.
2
Format Outbound Numbers
Telephony routes globally. Ensure all recipient numbers are stored and transmitted in standard E.164 formats (e.g. `+1` prefix for US, `+61` for AU).
3
Verify Latency Performance
WebRTC streams automatically hit the nearest regional LiveKit media server. For API calls, measure request latency to `api.langoedge.com` from your server environment to verify it meets your application needs.
4
Configure Webhooks for State Changes
Set up an HTTPS webhook to listen to variables written to the agent's state notepad during conversation execution.
Frequently Asked Questions
Why does the text API return a 403 Forbidden error?
Make sure you are passing both `x-langoedge-secret` and `x-langoedge-user-id` in the request headers. Additionally, make sure the parameters are passed as Form data (x-www-form-urlencoded), not JSON body.
Can I fetch chat history programmatically?
Yes! You can fetch voice session details and transcripts using `GET /voice-graphs/{voice_graph_id}/chat-history/external` with your secure headers.
What is the response format of the outbound dialer?
A successful dispatch returns `{"status": "ok", "message": "Call dispatched successfully"}` indicating the voice room has queued the request to call the phone trunk.
Can I stream text responses using secret-based authentication?
No. Langoedge's external API gateway (`api.langoedge.com`) does not support streaming (SSE) for requests authenticated via `x-langoedge-secret` headers. External integrations are strictly non-streaming.