curl --request POST \
--url https://b.anny.co/api/voice/incoming-call \
--header 'Content-Type: application/json' \
--header 'X-Anny-Signature: <api-key>' \
--data '
{
"called_number": "+4930123456789",
"caller_number": "+4915112345678",
"caller_anonymous": false,
"channel": "phone",
"provider_call_id": "hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P"
}
'{
"default_language": "de",
"instructions": "You are the AI receptionist for Glow & Co. Greet the caller in German. Use the booking-management MCP tools to look up availability and create bookings…",
"instructions_format": "text",
"tools": [
{
"type": "mcp",
"server_label": "booking-management",
"server_url": "https://b.anny.co/mcp/customer",
"require_approval": "never",
"allowed_tools": [
"get_organization",
"list_services",
"get_availability_intervals",
"add_booking",
"send_booking_link"
],
"headers": {
"X-Call-Context-Payload": "eyJvcmciOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJjYWxsX3Nlc3Npb24iOiI3YzNlMmYxYS00ZDhiLTRlMmMtOWY1YS0xYjZkOGUwYzJhNDcifQ==",
"X-Call-Context-Signature": "3f9b8c4e1d2a6f5b7c8e9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
"X-Tenant-ID": "550e8400-e29b-41d4-a716-446655440000",
"Mcp-Session-Id": "8a1f2b3c-4d5e-6f70-8192-a3b4c5d6e7f8"
}
}
],
"call_session_id": "7c3e2f1a-4d8b-4e2c-9f5a-1b6d8e0c2a47"
}Bootstrap an incoming voice call
Called by the HiDesk telephony platform when a call arrives on an anny Phone number.
anny resolves the dialed number to an organization, builds the agent configuration for the call, and returns:
- the agent
default_languageand fullinstructions(system prompt), - the MCP
tools(server definitions, allowlists, signed call-context headers) the agent may use during the conversation, - the anny-internal
call_session_idthat must be echoed back in the post-call webhook.
Authentication
The request body is signed by HiDesk with HMAC-SHA256 using the shared secret configured during onboarding. The hex-encoded digest is sent in the X-Anny-Signature header.
anny verifies the signature against the raw request body before any JSON parsing. If verification fails the response is 401 Unauthorized.
Tool headers
Each entry in tools[].headers already contains everything HiDesk needs to call the MCP server on the agent’s behalf:
| Header | Description |
|---|---|
X-Call-Context-Payload | Base64-encoded call context (organization, call session, caller metadata) — signed by anny |
X-Call-Context-Signature | HMAC-SHA256 signature of the payload — signed by anny |
X-Tenant-ID | anny organization external ID, required by every MCP request |
Mcp-Session-Id | UUID identifying this MCP session — keep stable for the duration of the call |
Forward tools[].headers verbatim on every MCP request. Do not strip, reorder, or mutate them — the signature is computed over the exact X-Call-Context-Payload value.
curl --request POST \
--url https://b.anny.co/api/voice/incoming-call \
--header 'Content-Type: application/json' \
--header 'X-Anny-Signature: <api-key>' \
--data '
{
"called_number": "+4930123456789",
"caller_number": "+4915112345678",
"caller_anonymous": false,
"channel": "phone",
"provider_call_id": "hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P"
}
'{
"default_language": "de",
"instructions": "You are the AI receptionist for Glow & Co. Greet the caller in German. Use the booking-management MCP tools to look up availability and create bookings…",
"instructions_format": "text",
"tools": [
{
"type": "mcp",
"server_label": "booking-management",
"server_url": "https://b.anny.co/mcp/customer",
"require_approval": "never",
"allowed_tools": [
"get_organization",
"list_services",
"get_availability_intervals",
"add_booking",
"send_booking_link"
],
"headers": {
"X-Call-Context-Payload": "eyJvcmciOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJjYWxsX3Nlc3Npb24iOiI3YzNlMmYxYS00ZDhiLTRlMmMtOWY1YS0xYjZkOGUwYzJhNDcifQ==",
"X-Call-Context-Signature": "3f9b8c4e1d2a6f5b7c8e9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
"X-Tenant-ID": "550e8400-e29b-41d4-a716-446655440000",
"Mcp-Session-Id": "8a1f2b3c-4d5e-6f70-8192-a3b4c5d6e7f8"
}
}
],
"call_session_id": "7c3e2f1a-4d8b-4e2c-9f5a-1b6d8e0c2a47"
}Autorisierungen
HMAC-SHA256 signature of the raw request body, computed with the shared HiDesk integration secret and sent as a lowercase hex string.
Verified by anny before JSON parsing. Mismatch → 401 Unauthorized.
Header
Hex-encoded HMAC-SHA256 of the raw request body, computed with the shared HiDesk integration secret.
^[A-Fa-f0-9]{64}$Body
The anny Phone number that was dialed, in E.164 format (+ followed by 5–15 digits, leading digit non-zero).
^\+[1-9]\d{4,14}$"+4930123456789"
HiDesk's unique identifier for this call. anny uses this value for deduplication against the post-call webhook.
255"hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P"
Caller's phone number. Send null when the caller withheld their number.
30"+4915112345678"
Whether the caller withheld their number. When true, caller_number must be null.
Originating channel for the call.
phone, web, native Antwort
OK — agent configuration returned. HiDesk should start the AI conversation with these instructions and tools.
BCP-47 language tag the agent should open the call with. Customers may switch language mid-call.
"de"
Full system prompt for the AI agent. Organization-specific and built per call — do not cache across calls.
MCP server definitions the agent may use during the call. Headers are pre-signed and call-scoped.
Show child attributes
Show child attributes
anny-internal session ID. Must be echoed back as call_session_id in the post-call webhook so anny can correlate metadata and recording with the conversation state.
"7c3e2f1a-4d8b-4e2c-9f5a-1b6d8e0c2a47"
Format hint for instructions. Currently always text.
text, markdown