Events and logs

Inbound calls

Have one of your agents answer a phone number. Inbound calls run the same pipeline as outbound ones and produce the same events, transcript and log.

How it works

Assign a number to an agent with POST /v1/phone-numbers.
At your carrier, set that number's answer URL to https://<your-host>/v1/telephony/inbound.
When someone calls, Offhook checks the carrier's signature, finds the agent for the dialed number, and connects the call.

Assign a number

POST /v1/phone-numbers

Body parameters

Field	Type	Description
`e164`required	string	The number in E.164 format, e.g. `+14155550123`.
`agent_id`required	uuid	The agent that answers calls to this number. It needs a telephony connection for the same carrier.

curl -X POST http://localhost:8000/v1/phone-numbers \
  -H "Authorization: Bearer $OFFHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "e164": "+14155550123", "agent_id": "<agent-id>" }'

{
  "id": "9d3c7e1a-4f2b-4d8e-b5a9-1c6e3f8d2a70",
  "e164": "+14155550123",
  "agent_id": "3b9e2a7c-1d4f-4e8a-b6c2-5f7a9d1e3c40",
  "created_at": "2026-10-15T10:00:00Z"
}

A number can belong to only one agent. Assigning a number that's already taken returns 409.

List and delete

GET /v1/phone-numbers

DELETE /v1/phone-numbers/{id}

Inbound calls appear in your call list with "direction": "inbound", and each one sends a call.received event when it arrives.