Set Contact Resolver | SpeechifyAI API

Configure the endpoint Speechify asks to identify an inbound caller.

On an inbound call from a number nobody has linked yet, Speechify POSTs {channel, identifier, agent_id, conversation_id} to this URL, signed with the same Speechify-Signature scheme as webhooks, and expects {external_id, display_name?, variables?} back. The contact attaches before the first token is generated, so {{memory}} is populated on the agent’s opening line.

The call FAILS OPEN on a sub-second deadline. A slow, unreachable or malformed response degrades to a call with no contact and no memory block - never a failed call and never a delayed answer. Answers are cached briefly per (workspace, identifier kind, identifier value), so a repeat caller does not re-hit your backend; they are scoped to the configuration that produced them, so changing the URL takes effect at once rather than after the cache window.

One resolver per workspace: this endpoint sets it, and re-sending the same body is a no-op. Configuring for the first time mints a signing secret and returns it once; later edits keep the secret you already deployed a verifier against and return it blank.

The URL must be https and must resolve to a public address. A loopback, private-range or cloud-metadata host is rejected here, and blocked again at dial time.

Configure the endpoint Speechify asks to identify an inbound caller. On an inbound call from a number nobody has linked yet, Speechify POSTs `{channel, identifier, agent_id, conversation_id}` to this URL, signed with the same `Speechify-Signature` scheme as webhooks, and expects `{external_id, display_name?, variables?}` back. The contact attaches before the first token is generated, so `{{memory}}` is populated on the agent's opening line. The call FAILS OPEN on a sub-second deadline. A slow, unreachable or malformed response degrades to a call with no contact and no memory block - never a failed call and never a delayed answer. Answers are cached briefly per (workspace, identifier kind, identifier value), so a repeat caller does not re-hit your backend; they are scoped to the configuration that produced them, so changing the URL takes effect at once rather than after the cache window. One resolver per workspace: this endpoint sets it, and re-sending the same body is a no-op. Configuring for the first time mints a signing secret and returns it once; later edits keep the secret you already deployed a verifier against and return it blank. The URL must be `https` and must resolve to a public address. A loopback, private-range or cloud-metadata host is rejected here, and blocked again at dial time.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Request

This endpoint expects an object.

urlstringRequiredformat: "uri"<=2048 characters

HTTPS endpoint that answers {external_id, display_name?, variables?}. Must resolve to a public address - loopback, private-range and cloud-metadata hosts are rejected.

disabledbooleanOptionalDefaults to false

Park the integration without deleting it. Defaults to false.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

The stored configuration. secret is present only when this call created the configuration; store it, it is not shown again.

urlstringformat: "uri"

The HTTPS endpoint Speechify POSTs the identifier to.

disabledboolean

When true the endpoint is kept but never called, which is how you park an integration without losing its secret.

created_atdatetime

updated_atdatetime

secretstringOptional

The HMAC signing key, present ONLY in the response that mints it (first configuration, or a rotation). Verify Speechify-Signature with it exactly as you would a webhook.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error