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"
}

Integrations & Apps

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_language and full instructions (system prompt),
the MCP tools (server definitions, allowlists, signed call-context headers) the agent may use during the conversation,
the anny-internal call_session_id that 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.

POST

api

voice

incoming-call

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

X-Anny-Signature

string

header

erforderlich

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

X-Anny-Signature

string

erforderlich

Hex-encoded HMAC-SHA256 of the raw request body, computed with the shared HiDesk integration secret.

Pattern: ^[A-Fa-f0-9]{64}$

Body

application/json

called_number

string

erforderlich

The anny Phone number that was dialed, in E.164 format (+ followed by 5–15 digits, leading digit non-zero).

Pattern: ^\+[1-9]\d{4,14}$

Beispiel:

"+4930123456789"

provider_call_id

string

erforderlich

HiDesk's unique identifier for this call. anny uses this value for deduplication against the post-call webhook.

Maximum string length: 255

Beispiel:

"hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P"

caller_number

string | null

Caller's phone number. Send null when the caller withheld their number.

Maximum string length: 30

Beispiel:

"+4915112345678"

caller_anonymous

boolean

Standard:false

Whether the caller withheld their number. When true, caller_number must be null.

channel

enum<string>

Standard:phone

Originating channel for the call.

Verfügbare Optionen:

phone,

web,

native

Antwort

OK — agent configuration returned. HiDesk should start the AI conversation with these instructions and tools.

default_language

string

erforderlich

BCP-47 language tag the agent should open the call with. Customers may switch language mid-call.

Beispiel:

"de"

instructions

string

erforderlich

Full system prompt for the AI agent. Organization-specific and built per call — do not cache across calls.

tools

object[]

erforderlich

MCP server definitions the agent may use during the call. Headers are pre-signed and call-scoped.

Show child attributes

call_session_id

string<uuid>

erforderlich

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.

Beispiel:

"7c3e2f1a-4d8b-4e2c-9f5a-1b6d8e0c2a47"

instructions_format

enum<string>

Standard:text

Format hint for instructions. Currently always text.

Verfügbare Optionen:

text,

markdown

Guides

Customer API

Admin API

Data models

Customer internal API

Admin internal API

Identity API

Additional internal API

Bootstrap an incoming voice call

Authentication

Tool headers

Autorisierungen

Header

Body

Antwort