Dynamic SIP Endpoint

A dynamic SIP webhook lets one agent reach a different SIP destination on every call. Instead of configuring a fixed SIP URI, you give Bluejay a webhook URL. Right before each call dials, Bluejay POSTs that URL and dials whatever sip_uri (or phone_number) it returns. Use this when each conversation needs its own room or endpoint — for example a fresh per-call SIP address minted by your platform — without creating a separate agent or simulation run per URI.

This is an alternative to a static SIP URI, not an addition. An agent has either a fixed sip_uri or a dynamic_sip_webhook_url, never both.

How It Works

Fetch — at dial time, for each call, Bluejay POSTs your webhook URL.
Resolve — your endpoint returns the SIP URI (or phone number) to dial for this specific call.
Dial — Bluejay dials the returned destination and the simulation proceeds like any SIP call, including the injected X-Simulation-Result-Id header.

If the fetch fails after retries, the call is marked NO_CONNECTION with error code DYNAMIC_ENDPOINT_FAILED — Bluejay fails loudly rather than dialing a stale endpoint. There is no static fallback.

Setup

Host your webhook

Expose an HTTPS endpoint that Bluejay can reach from the public internet. It must accept a POST with a JSON body and return the destination for the call. See Webhook Contract below.

Let an AI build it for you. Paste the prompt below into any coding assistant (Claude, Cursor, Copilot, etc.) — it fully specifies the contract, so you just add your own logic for choosing the SIP URI.

Prompt: generate a Bluejay dynamic SIP webhook

Build an HTTP webhook endpoint for Bluejay's "dynamic SIP endpoint" feature in <your language/framework, e.g. Python + FastAPI>.

Requirements:
- Expose a single POST route (e.g. POST /bluejay/sip-endpoint) that accepts a JSON body:
  { "test_result_id": string, "experiment_run_id": number, "agent_id": number,
    "organization_id": string, "nonce": string, "timestamp": string (ISO 8601) }
- Respond 200 with JSON containing the SIP destination to dial for THIS call:
  { "sip_uri": "sip:<room>@<host>" }
  (Optionally instead return { "phone_number": "+1..." }, and optionally include
   "sip_username", "sip_password", "custom_headers": {..}, "metadata": {..}.)
- Idempotency: the endpoint may be retried for the same "test_result_id" (up to 3x with
  backoff). It MUST return the SAME sip_uri for a given test_result_id — key any room
  allocation on test_result_id and return the existing value on a retry, never mint a new one.
- Leave a clearly marked TODO where I plug in my logic that maps a call to a SIP URI
  (e.g. allocate/look up a room). For now, default to returning a placeholder sip_uri.
- Must be deployable behind public HTTPS. Return 5xx only on genuine errors (Bluejay
  fails the call loudly after 3 failed attempts).
- Optional security: if I set an env var BLUEJAY_WEBHOOK_SECRET, verify the request's
  "X-Bluejay-Signature" header as HMAC-SHA256(secret, raw_request_body) and reject on mismatch.
- Include a one-line run command and a curl example that exercises the endpoint.

Configure your agent

Set dynamic_sip_webhook_url on the agent. Providing it makes the agent a SIP agent automatically.

Website
API
MCP

Open Agent Settings → Connection, choose SIP as the connection type, and paste your endpoint into Dynamic SIP Webhook URL. Leave the static SIP URI field blank.

curl -X POST https://api.getbluejay.ai/v1/add-agent \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My SIP Agent",
    "system_prompt": "...",
    "knowledge_base": "...",
    "goals": ["..."],
    "dynamic_sip_webhook_url": "https://your-service.com/bluejay/sip-endpoint"
  }'

To set it on an existing agent, use /v1/update-agent with agent_id and dynamic_sip_webhook_url.

Pass dynamic_sip_webhook_url to the add_agent or update_agent tool.

Run a simulation

Create a simulation and queue runs as usual — see Simulations. Each call independently fetches its own destination from your webhook.

Webhook Contract

Request

Bluejay sends a POST with Content-Type: application/json:

{
  "test_result_id": "583149",
  "experiment_run_id": 163456,
  "agent_id": 22330,
  "organization_id": "fb838ba6-...",
  "nonce": "583149",
  "timestamp": "2026-07-07T21:43:48.461190+00:00"
}

Field	Description
`test_result_id`	Unique ID for this call. Use it as your idempotency key.
`experiment_run_id`	The simulation run this call belongs to.
`agent_id`	The Bluejay agent being dialed.
`organization_id`	Your organization ID.
`nonce`	Equal to `test_result_id`; safe to treat as the idempotency key.
`timestamp`	ISO 8601 UTC time the request was issued.

Response

Return 200 OK with a JSON object containing sip_uri (or phone_number):

{
  "sip_uri": "sip:[email protected]",
  "sip_username": "optional-per-call-user",
  "sip_password": "optional-per-call-secret",
  "custom_headers": { "X-Your-Header": "value" },
  "metadata": { "room": "abc" }
}

Field	Required	Description
`sip_uri`	one of `sip_uri` / `phone_number`	SIP destination to dial for this call.
`phone_number`	one of `sip_uri` / `phone_number`	Phone number to dial instead of a SIP URI.
`sip_username`	optional	Per-call SIP auth username.
`sip_password`	optional	Per-call SIP auth password.
`custom_headers`	optional	Extra headers merged into the SIP INVITE.
`metadata`	optional	Echoed back and stored on the test result for your reference.

The endpoint must be idempotent on test_result_id. Bluejay retries with exponential backoff (3 attempts), so a given test_result_id must always resolve to the same destination — return the room you already minted rather than allocating a new one on a retry.

Security

Bluejay POSTs your endpoint from its own infrastructure, so treat it like any inbound webhook: restrict who can reach it. Where a shared signing secret is available for your agent, Bluejay signs the request body with HMAC-SHA256 and sends it in the X-Bluejay-Signature header — verify it the same way as other Bluejay webhooks. If no signing secret is configured, requests are sent unsigned; in that case gate access with an allowlist or a secret embedded in the URL path.

Troubleshooting

Symptom	Cause	Fix
Call ends immediately as `NO_CONNECTION` / `DYNAMIC_ENDPOINT_FAILED`	Webhook returned non-2xx, timed out, or returned no `sip_uri`/`phone_number` after 3 attempts	Confirm the endpoint is publicly reachable and returns a valid destination JSON.
Same call dialed a stale/wrong room on retry	Endpoint is not idempotent on `test_result_id`	Key your room allocation on `test_result_id` and return the same value across retries.
Webhook never called	Agent has a static `sip_uri` set, or connection type isn’t SIP	Clear `sip_uri`; setting `dynamic_sip_webhook_url` alone infers SIP.

Getting Started

Key Concepts

Test

Monitor

Integrations

Dynamic SIP Webhook

Dynamic SIP Endpoint

How It Works

Setup

Webhook Contract

Request

Response

Security

Troubleshooting

​Dynamic SIP Endpoint

​How It Works

​Setup

​Webhook Contract

​Request

​Response

​Security

​Troubleshooting

Dynamic SIP Endpoint

How It Works

Setup

Webhook Contract

Request

Response

Security

Troubleshooting