Skip to main content

​
Client Integration

In the code that calls your agent, replace the agent URL with the Convoy proxy URL. This is the only change needed on the client side.

​
What to change

BeforeAfter
Send to your agent URL directlySend to the Convoy proxy URL from agent settings
—Add Session-ID header
—Add Authorization: Bearer <secret> header
  • Proxy URL: Get this from your agent settings in the Convoy platform (format: {org}--{agent}.proxy.convoylabs.com)
  • Session-ID: A unique identifier for this session. Alphanumeric, hyphens, underscores, and dots. Max 255 characters. Convoy uses this to route the same session to the same version consistently.
  • Authorization: The shared secret from your agent settings, passed as a bearer token. Store it as an environment variable.
  • Body: Unchanged — send whatever your agent expects.
Convoy routes the request to the correct version (stable or test) and forwards it to your agent backend.

​
Code examples

const response = await fetch(process.env.CONVOY_PROXY_URL!, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Session-ID": sessionId,
    "Authorization": `Bearer ${process.env.CONVOY_SECRET}`,
  },
  body: JSON.stringify({ input: userMessage }),
});
Environment variables used:
  • CONVOY_PROXY_URL — the proxy URL from your agent settings
  • CONVOY_SECRET — the shared secret from your agent settings