Skip to main content
Chat API Call steps, pre/post API actions, workflow tools and voice custom functions can call your services.

​
Secret headers

Where a header editor is available, turn on the row’s Secret switch. The value is encrypted and never shown again. Saved values stay on the server. Request logs show secret values as [secret] and signatures as [signature]. Workflow tools have no header editor. Their configured headers are literal values. Workflow requests are still signed.

​
Signing and reserved names

Agent requests use the organization’s Request signing secret in Settings → Integrations → Signing secrets. Verify them with the shared recipe. During rotation, requests include signatures for both current and retiring secrets. These names are reserved, regardless of case:
  • X-Tars-Signature
  • X-Tars-Event-Id
  • X-Tars-Request-Id
  • X-Tars-Conversation-Id
  • X-Tars-Call-Id
  • X-Tars-Delivery-Id
Voice custom functions also reserve Content-Type. Chat requests can set their own Content-Type. X-Tars-Request-Id identifies the logical request and stays the same on retries. Conversation and call headers appear when applicable.

​
Inbound call check

Configure an HTTPS check URL on an inbound phone number. Tars calls it before choosing how to handle the incoming call. The check sends POST once with a five-second timeout. Verify its signature using the organization’s Request signing secret.

​
Request body

​
Accept

Return a 2xx application/json response containing an empty object to keep the number’s normal binding.

​
Reject

Return reject.reason as a non-empty string. This ends the call with rejected_by_webhook.

​
Override

Return an override object with optional agentId, variables, metadata, language and storageMode.
variables is a map of string values. storageMode is everything, everything_except_pii or basic_attributes_only. The override agent must be active, published, in the same organization and eligible for inbound calls. An invalid override falls back to the normal binding.

​
Failure behavior

Timeouts, connection errors, non-2xx responses, invalid JSON and missing signing configuration fall back to the number’s normal binding. Redirects are not followed. There is one attempt, so the check must respond promptly.