#How to connect to the webscket url wss://api.elevenlabs.io/v1/convai/conversation in nodejs

1 messages · Page 1 of 1 (latest)

meager socketBOT
#
AI-generated Answer for miky2fois

Below is the minimal, doc‑aligned way to open a Node.js WebSocket to the ElevenLabs Conversational AI endpoint.

  1. Decide how you will authenticate
  • Public agent: connect directly with the agent_id query param: wss://api.elevenlabs.io/v1/convai/conversation?agent_id=YOUR_AGENT_ID. (elevenlabs.io)
  • Private agent (recommended for client apps): have your server fetch a short‑lived signed URL, then connect with that URL from your Node client. Do not expose your API key to the client. (elevenlabs.io)

Example (Node server) – get a signed URL

  1. Connect from Node and start the session
  • Open a WebSocket to either the signed URL or the agent_id URL.
  • Immediately send a conversation_initiation_client_data message to begin the session. (elevenlabs.io)

Example (Node client) – using any standard WebSocket library

  • After open: send { "type": "conversation_initiation_client_data" }.
  • Send user text: { "type": "user_message", "text": "Hello" }.
  • Send audio: { "user_audio_chunk": "<base64 audio>" }.
  • Reply to server pings with: { "type": "pong", "event_id": <from ping_event> }. (elevenlabs.io)
  1. Handle server events
  • Expect events like conversation_initiation_metadata, user_transcript, agent_response, audio (with audio_base_64), interruption, and ping. (elevenlabs.io)

Reference docs

  • WebSocket endpoint and auth patterns (agent_id vs signed URL), plus example flow and Next.js snippet. (elevenlabs.io)
  • Agent WebSockets API reference (handshake, required query param, message schemas for send/receive, ping/pong). (elevenlabs.io)
  • Get Signed URL endpoint details (method, headers, parameters, deprecation note of snake_case path). (elevenlabs.io)
  • React/JS SDK pages show the exact server call for /get-signed-url and using the signedUrl for a websocket session. (elevenlabs.io)

If you want code lifted directly from the docs, the Next.js snippet shows the same WebSocket messages and ping/pong handling; you can mirror the same JSON messages

austere quarry
#

Why my webhooks (pre/post call) are not triggered?

meager socketBOT
#
AI-generated Answer for miky2fois

Short answer: most “missing” webhooks are due to configuration or delivery constraints documented by ElevenLabs. Use this checklist.

Pre-call (conversation initiation) webhooks

  • They exist only for inbound Twilio calls. You must: 1) configure the webhook URL in Agents Platform settings, and 2) enable “Fetch conversation initiation data” in the agent’s Security tab. If you’re using the web widget, SIP/connector, or raw WebSocket, there is no server-side pre-call webhook; send conversation_initiation_client_data over the WebSocket instead. (elevenlabs.io)
  • Your endpoint must respond quickly with the expected JSON; slow or no response can cause the call to proceed without your data. (elevenlabs.io)

Post-call webhooks

  • Triggers only after the call ends and analysis finishes. If the call fails to initiate, you’ll get the separate call_initiation_failure event; voicemail/IVR doesn’t count as a failure, so no failure webhook is sent in that case. (elevenlabs.io)
  • Enable them in Agents Platform settings. If you expect full audio, also enable “Send audio data.” Audio webhooks are streamed (Transfer-Encoding: chunked), so your server must accept and parse chunked bodies. (elevenlabs.io)
  • Be aware of the ongoing migration: post_call_transcription payloads include extra has_audio flags from August 15, 2025. Strict parsers that reject unknown fields will fail. (elevenlabs.io)

All webhooks (delivery requirements)

  • Your handler must return HTTP 200 promptly. Each event is sent once; for HIPAA compliance, failed deliveries are not retried. After ≥10 consecutive failures and no success for >7 days (or never), a webhook is auto‑disabled and must be re‑enabled in settings. (elevenlabs.io)
  • Validate HMAC signatures from the ElevenLabs-Signature header (hash of timestamp.request_body). A bad signature that causes non‑200 responses will count as a failure. (elevenlabs.io)
  • If you firewall inbound traffic, allow ElevenLabs’ static egress IPs (per region) or requests will never reach you. (elevenlabs.io)
  • For local development, expose a public HTTPS URL (e.g., ngrok) or the platform cannot call your endpoint. (elevenlabs.io)

Platform health

  • Check the status page if you suspect a service issue; e.g., there was a post-call webhook incident on July 9, 2025 (resolved). (status.elevenlabs.io)

If you share which path you’re using (inbound Twilio vs. WebSocket/browser; and which post-call types you enabled), I can map your setup to the exact doc sections above.

austere quarry
#

Why web calls don't trigger webhooks?

meager socketBOT
#
AI-generated Answer for miky2fois

Short answer: “Web calls” made over the Agents Platform WebSocket do not trigger the Twilio “pre‑call” webhook (that webhook is telephony‑only). “Post‑call” webhooks do trigger for Agents Platform conversations (including web/WebSocket) if they’re enabled and your endpoint is healthy.

Why you may see no webhook:

  • Pre‑call webhook doesn’t apply to web: The “Twilio personalization” pre‑call webhook is only invoked for inbound Twilio phone calls, not for WebSocket conversations.
  • Post‑call not enabled or overridden: Post‑call webhooks must be enabled in Agents Platform settings; they can also be overridden per‑agent. Verify workspace settings and any agent‑level overrides.
  • Endpoint not reachable or not returning 200: ElevenLabs considers a delivery successful only if your listener quickly returns HTTP 200. Webhooks that fail 10+ times consecutively are auto‑disabled until you re‑enable them.
  • No retries under HIPAA: If enabled for HIPAA, failed post‑call webhooks are not retried—temporary outages will result in no delivery.
  • Local development URL: The callback must be publicly accessible (e.g., expose localhost via ngrok) for deliveries to reach you.
  • Channel confirmation: If you’re initiating “web calls,” that’s the Agents Platform WebSocket at wss://api.elevenlabs.io/v1/convai/conversation; pre‑call webhooks won’t run on this channel by design.
  • Rare platform incidents: If everything is configured correctly, check the status page for any recent webhook delivery incidents.

If you want post‑call data for web/WebSocket conversations, enable post‑call webhooks in Agents Platform, ensure your endpoint returns 200 quickly, and confirm the webhook wasn’t auto‑disabled.

austere quarry
#

Is it possible to get agents information from a tool call webhook?

meager socketBOT
#
AI-generated Answer for miky2fois

Short answer: yes, but not automatically.

What’s documented

  • Tool webhooks send exactly what you define in the tool’s API schema. To include agent/conversation context in the request your server receives, add dynamic variables to the tool’s headers, path, query, or body (for example, system__agent_id, system__current_agent_id, system__conversation_id). These system variables are provided by the platform at tool-call time. (elevenlabs.io)
  • Dynamic variables use the {{ variable_name }} syntax, so you can configure headers like X-Agent-Id: {{ system__agent_id }} or payload fields using the same pattern. (elevenlabs.io)

If you need full agent details (name, config, etc.)

  • Use the agent ID you passed in the webhook request to call the API from your server: GET /v1/convai/agents/:agent_id. (elevenlabs.io)

Related note

  • Post‑call webhooks (not tool calls) include agent_id in their payloads by default, but that’s for after-call analytics, not during a tool invocation. (elevenlabs.io)

In summary: include the agent identifiers yourself via dynamic variables in the tool configuration, then fetch any additional agent information you need from GET /agents. (elevenlabs.io)

Sources:
Server tools | ElevenLabs Documentation
Personalization | ElevenLabs Documentation
Get agent | ElevenLabs Documentation
Post-call webhooks | ElevenLabs Documentation
Dynamic variables | ElevenLabs Documentation

austere quarry
#

show me a tool schema example that includes system__agent_id