Skip to main content
Custom API tools let a voice agent read or update data in an external system during a call. Use them for account lookups, identity checks, payment commitments, case creation, or a service your organization exposes through an API. The endpoint supplies the business behavior. Revve configures when to call it, sends the required fields, and makes its response available to the conversation. An integration does not require a dedicated connector for every business operation.

​
Configure a tool

Open the voice agent’s Advanced Settings, go to Tools, and choose Add to create a custom API call.
  1. Give the tool a unique name and a description explaining when the agent should use it.
  2. Set the destination URL and HTTP method.
  3. Add the headers required by the service. Keep credentials in the request configuration, outside the spoken instructions.
  4. Define request fields. Use AI Generated for information the agent collects from the caller, and Fixed Value for configured values or supported variable templates.
  5. Have the endpoint return a compact response with an explicit outcome and the fields the agent needs. Normalize complex responses in your API or integration gateway.
  6. Set a Tool Call Message if the caller should hear a short acknowledgment while the request runs.
  7. Save the tool and test it with the agent’s draft before publishing.
Configured request fields form the request body; they are not automatically converted into GET query parameters. If a service requires query parameters, include them in the URL using supported variable templates, or expose a compatible POST endpoint through your gateway. Test the received URL and body against the service’s contract.

​
Use custom business fields

Combine contact fields, conversation fields, and call analysis to represent your organization’s data. For example, a collection workflow can store a customer reference, days past due, asset description, promised payment date, and case status. Use the field types offered by each editor. Structured domain data can be represented with multiple fields or a serialized value according to the integration contract. The API remains the source of truth for balances, permissions, and transaction status.

​
Map results and route the conversation

Return a clear status such as verified, rejected, or unavailable, together with the values the conversation needs. The shared tool editor exposes Result Mapping, but the Revve voice runtime does not apply it. Normalize responses in the receiving API or gateway; use flow logic and Code nodes for additional deterministic handling. A typical account-service flow is:
  1. Collect the customer reference.
  2. Call the identity service and inspect its result.
  3. Retrieve the permitted account information.
  4. Read back the requested action and obtain confirmation.
  5. Call the action endpoint and explain its returned outcome.
Connect explicit failure paths for missing fields, rejected verification, unavailable services, and ambiguous results. Return partial-success details per item when an operation can succeed for some accounts and fail for others.

​
Integrate through an existing gateway

The tool calls HTTP endpoints. A GraphQL service can be called through its HTTP interface using the query and variables required by that service. For SOAP, gRPC, private networks, or specialized authentication, expose a compatible HTTP interface through your integration gateway and keep protocol conversion there. This is an integration pattern; it does not turn Revve’s own API into a native gRPC service. The same approach connects core banking, CRM, messaging, identity providers, fraud engines, and enterprise notification services. Configure proxy access when the destination requires it.

​
Design retries and reconciliation

For an operation that changes data, send a stable request identifier and have the receiving service enforce idempotency. A timeout does not prove that the operation failed: query its status before repeating it. Carry the same correlation identifier into the external record so operators can reconcile the call with the transaction. Use automation API actions for post-call synchronization, notifications, and retry policies. For example, a Call Analyzed event can send the summary and extracted fields to a CRM. This event runs after analysis, so it should not be used as an acknowledgment for a transaction that the caller needs confirmed during the call.

​
Validate the integration

Test success, rejected authorization, missing data, timeout, duplicate submission, and partial failure. Voice evaluations can check that the expected tool was called and that the agent responded appropriately. Publish the tested agent version using Voice Agent Versioning; users without Publish Agents submit the draft through the approval workflow.