Skip to main content
An HTTP tool queries or updates your system during the conversation. The agent decides when to invoke it from its description and instructions. Your endpoint returns information the agent uses to continue.

​
Choose the agent type

Add a Custom tool. Save and publish the agent. Your endpoint receives a POST with call, tool_name, and args.Configure voice tools · Inspect voice fields

​
Walkthrough: look up an order

1

Define what your API needs

Create lookup_order with a required order_number parameter. Describe when to use it and how to request missing information.
2

Separate parameters from context

The order number arrives in args.order_number. ContactShip adds call or thread separately. Customers do not need to provide internal IDs.
3

Query your system

Your receiver reads arguments, validates input, and finds the order. Correlate diagnostic records using call.call_id or thread.id.
4

Return a useful result

Respond with valid JSON and concrete data. If the order does not exist, return that outcome. Avoid empty responses that leave the agent guessing.
5

Test the complete conversation

Check connectivity in the configurator. Then run a controlled conversation and inspect the actual request and response.
Response fields illustrate your own contract; they are not required ContactShip fields. Configure instructions to interpret both outcomes.

​
Where each value comes from

Context depends on the case. Web voice calls can have empty phone numbers. Text channel information can be missing. Inspect the complete fields and examples.

​
What each test demonstrates

HTTP test buttons send real requests. Voice tests use configured headers, but live execution currently does not forward them to your endpoint. If your integration requires header authentication, coordinate with support and verify a real call.

​
Tool, webhook, or automation

I need data during the conversation

Use a tool and return its result in the HTTP response.

I need to act after completion

Choose the webhook matching the event and its contract.

I need an inbox rule

Configure a trigger, conditions, and actions.

I need a follow-up

Choose an event and map the data that determines the action.

​
Frequently asked questions

No. Configure only the arguments your tool needs to extract. ContactShip adds the corresponding context.
The tool expects a response during this execution. For long jobs, return a truthful pending state and your own reference. Design delivery of the final result separately.
Use endpoint logs or workflow execution history. For text, also compare the configurator payload. Post-call webhook history represents a separate event.
A conversation can legitimately invoke the same tool multiple times. For operations that create records or charge customers, use a business operation identifier and store its result.