Functions and tools

Let an agent call your API, a calendar, an MCP server, or control the call itself.

A function is something the agent can do during a call. The model decides when to use it, from the function's name and description. Functions belong to one agent.

Kind	Use it to
`custom`	Call your own HTTP endpoint.
`end_call`	Hang up. Every agent has one already.
`transfer_call`	Transfer the caller to a number.
`press_digit`	Send touch-tones to an automated menu.
`agent_swap`	Hand the call to another agent.
Calendar kinds	Check availability and book on Cal.com or Google Calendar. Cancel and reschedule are Cal.com only.

For MCP servers, see below.

Call your own API

curl

curl https://api.dialgem.com/v1/agents/AGENT_ID/functions \
  -H "X-API-Key: $DIALGEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_order",
    "description": "Look up an order by its number. Use when the caller asks where their order is.",
    "url": "https://example.com/dialgem/lookup-order",
    "method": "POST",
    "parameters": {
      "type": "object",
      "properties": {
        "order_number": { "type": "string", "description": "The order number the caller gave." }
      },
      "required": ["order_number"]
    },
    "speak_during_execution": "One moment while I look that up."
  }'

name uses lowercase letters, digits and underscores, up to 64 characters, and cannot start with a digit.
description is what the model reads to decide when to call it. Write it as an instruction (up to 500 characters).
parameters is a JSON Schema for the arguments the model should collect.
speak_during_execution is a line the agent says while waiting. speak_after_execution (default true) lets the agent speak the result.
timeout_ms defaults to 10,000 and can be 100 to 300,000. The caller is waiting, so keep it short.
headers and query_params are lists of { "key", "value" } pairs, for example an authorization header.

What your endpoint receives

Dialgem sends one request to your URL with a JSON body:

json

{
  "name": "lookup_order",
  "call": { },
  "args": { "order_number": "12345" }
}

args holds what the model collected. call describes the call:

Field	Value
`call_id`, `agent_id`	Identifiers for the call and the agent.
`call_type`	`phone_call` or `web_call`.
`direction`	`inbound` or `outbound` (empty on web calls).
`from_number`, `to_number`	The two phone numbers.
`dynamic_variables`	The variables for this call.
`metadata`	The metadata set when the call was created.

The request also carries an X-Dialgem-Call-Id header. If your endpoint cannot accept extra fields, set args_at_root to send only the arguments object.

Verify the request

If the agent has a webhook_signing_secret, each request is signed with it in the X-Dialgem-Signature header, the same way as webhooks. Check it before acting, because the endpoint can change real data. The server SDK does this for you:

const { name, call, args } = await Dialgem.webhooks.constructFunctionCall(rawBody, req.headers["x-dialgem-signature"], secret)

A function with args_at_root has no call or name in the body, so use verify and parse the body yourself. A header you set that collides with X-Dialgem-Signature, Content-Type or X-Dialgem-Call-Id is ignored.

Reply with JSON or text. The agent reads your reply and uses it in its next sentence, so return short, plain facts.

Keep errors readable

If your endpoint fails or times out, the agent is told so and carries on. Return a clear message the agent can act on, such as "no order found", rather than an error page.

Control the call

These need a little configuration in config and ignore url, method and headers. Their description and parameters are filled in for you.

End call (end_call). Present on every agent. It cannot be renamed or deleted.
Transfer (transfer_call). config.transfer_destination needs a number (E.164, or a {{variable}}), a sip_uri, or "type": "inferred". See Voicemail and call transfer.
Press digit (press_digit). config.digits holds what to send, using only 0-9, * and #.
Agent swap (agent_swap). config.agent_id is the agent to hand to.

You cannot change a function's kind afterwards. Delete it and create a new one.

Calendars

Calendar functions need an API key or a saved connection in config, and are rejected when you save them if it is missing, rather than failing on a live call. Cal.com availability returns at most eight times, so the agent can read them aloud.

The easiest way is a saved connection: add a Cal.com key or connect a Google account once in Integrations, then set config.integration_id to it. Cal.com functions need a timezone (and, to check or book, an event_type_id); Google Calendar functions need an integration_id and a timezone.

MCP servers

An MCP server gives an agent a set of tools from a remote server that speaks the Model Context Protocol.

Add it with POST /v1/agents/{agent_id}/mcp-servers: a name (lowercase, digits, underscores, up to 48 characters), the url, and optionally an auth_token, headers, query_params and timeout_ms.
Check it with POST /v1/agents/{agent_id}/mcp-servers/{server_id}/test, and see its tools with GET .../tools.
Set enabled to false to turn it off without deleting it.

The auth_token is write-only: it is never returned. If a server cannot be reached during a call, its tools are left out and the call carries on.

Order and limits

Reorder functions with POST /v1/agents/{agent_id}/functions/reorder. Fewer, clearly named functions work better than many overlapping ones: the model has to choose between them in real time.