HTTP tool execution

A custom HTTP tool calls your endpoint during a conversation. These requests have no top-level data envelope. Voice uses call; text uses thread. Both include tool_name and args.

Set up an HTTP tool

Configure parameters, connect your system, and verify execution.

Post-call webhook

Use this separate contract for analysis after a call.

Voice request

Your endpoint receives a JSON POST. Example values below are fictional; optional values can be empty or absent.

{
  "call": {
    "call_id": "22222222-2222-4222-8222-222222222222",
    "agent_id": "11111111-1111-4111-8111-111111111111",
    "contactship_llm_dynamic_variables": {
      "customer_tier": "standard"
    },
    "call_status": "in_progress",
    "call_type": "api_call",
    "from_number": "+15555550101",
    "to_number": "+15555550102"
  },
  "tool_name": "lookup_order",
  "args": {
    "order_number": "ORD-1042"
  }
}

{
  "call": {
    "call_id": "22222222-2222-4222-8222-222222222222",
    "agent_id": "11111111-1111-4111-8111-111111111111",
    "contactship_llm_dynamic_variables": {},
    "call_status": "in_progress",
    "call_type": "test_web_call",
    "from_number": "",
    "to_number": ""
  },
  "tool_name": "lookup_order",
  "args": {
    "order_number": "ORD-1042"
  }
}

object

Context available during the call. This is not the analyzed post-call record.

Mostrar call

string

ContactShip call ID. Can be empty if the call record cannot be resolved.

string

ContactShip ID of the resolved active voice agent. After a handoff, it can identify the destination agent.

object

Variables available in this execution. Keys depend on call setup and context; there is no universal list of customer fields. Defaults to an empty object when unavailable.

string

State stored for the call when the tool executes. It can be empty. Do not treat it as the final outcome.

string

Stored call origin, such as api_call, inbound_call, or test_web_call. See call types. Can be empty if no record is resolved.

string | null

Source phone number. A web call can have an empty value.

string | null

Destination phone number. A web call can have an empty value.

string

Name of the invoked tool, as configured on the agent.

object

Arguments supplied for this invocation. Read configured inputs here, such as args.order_number. With no arguments, this can be {}.

Voice execution does not add a dedicated contact object, contact_id, transcript, recording, or final analysis. Dynamic variables may provide additional context, but do not assume those fields exist there.

The current voice execution path posts the body to the configured URL without forwarding configured tool headers or separate query parameters. Test endpoint can send them. A successful authenticated test therefore does not prove that a live call can authenticate. Coordinate header-based integration requirements with support.

Text request

The External API tool configured in the editor sends a JSON POST.

Text conversation

{
  "thread": {
    "id": "55555555-5555-4555-8555-555555555555",
    "contact_id": "33333333-3333-4333-8333-333333333333",
    "channel_type": "WABA",
    "channel_id": "66666666-6666-4666-8666-666666666666",
    "from_number": "+15555550102",
    "wa_id": "15555550102"
  },
  "tool_name": "lookup_order",
  "args": {
    "order_number": "ORD-1042"
  }
}

object

Conversation context. If context construction fails, the sender can fall back to a body containing only tool_name and args.

Mostrar thread

string

Conversation ID. The fallback value is unknown_thread when unavailable.

string | null

Associated contact ID when resolved. Fallback context can contain unknown_contact; do not use it as a real contact ID.

string | null

Channel type stored on the conversation. Can be null when context is unavailable.

string | null

Associated channel ID. Can be null.

string

Contact phone number, not the business channel’s number. Omitted when unavailable.

string

Contact WhatsApp identifier when available. Omitted for null or unavailable values.

tool_name is the configured tool name. args contains configured arguments; undeclared keys are not automatically forwarded. Missing optional arguments may be omitted. The current visual text editor configures parameters as strings. The standard body does not include a dedicated agent_id, organization ID, transcript, or conversation summary. Fetch other records through your integration when needed.

Your endpoint response

Return valid JSON containing the result the agent needs. These example fields belong to your contract, not a required ContactShip response schema.

{
  "found": true,
  "order_number": "ORD-1042",
  "status": "in_transit",
  "estimated_delivery": "2026-10-15"
}

{
  "found": false,
  "order_number": "ORD-1042",
  "reason": "No order matches this number"
}

ContactShip makes the returned result available to the agent. You do not need to wrap it in call, thread, or args. Use instructions that distinguish a missing record, an operation still pending, and a completed action. For text tools, successful responses normally become a tool result containing the HTTP status and response data. A plain non-JSON string can remain opaque text. Return JSON with the correct content type, especially from workflow response nodes. Text requests default to a 15-second timeout unless configuration changes it. Selected transient network failures and HTTP 429, 503, or 504 can trigger up to two additional HTTP attempts. This is not a guarantee about the total number of agent invocations. For operations with side effects, use your own business operation key and stored result. A call or conversation can legitimately invoke a tool multiple times; its ID alone is not an operation ID. The standard body supplies no dedicated unique tool-invocation ID.

Test requests versus live execution

Voice endpoint test
Text endpoint test

Test endpoint sends exactly the editable sample body. Initially it is built from parameter examples, without the live call, tool_name, or args wrapper. Edit it to resemble a full request when testing your parser.

Initial parameter sample

{
  "order_number": ""
}

The test sends configured headers, times out after 10 seconds, and does not follow redirects. It does not invoke the agent. Confirm the actual body and authentication through a controlled call.

External API → Test sends a fictional conversation and your entered argument values directly from the browser. The request can require CORS support.

Configurator test

{
  "thread": {
    "id": "test-thread-id",
    "contact_id": "test-contact-id",
    "channel_type": "TEST",
    "channel_id": "test-channel-id",
    "from_number": "+0000000000",
    "wa_id": "0000000000"
  },
  "tool_name": "lookup_order",
  "args": {
    "order_number": "ORD-1042"
  }
}

These identifiers are placeholders. Do not look them up as real ContactShip records. The text-agent chat sandbox instead simulates tool execution.

Find the data and diagnose failures

Need	Where to look
Set the endpoint and parameters	Voice tools or text tools
Inspect the actual received body and headers	Endpoint logs or workflow execution history
Find the contact from a text request	`thread.contact_id`, then get contact
Find the voice call record	`call.call_id`, then get call
Obtain final voice analysis	Post-call webhook, after the call

The test works, but the real call returns 401

Compare received headers. The voice configurator test and live execution handle configured headers differently. Check authentication with support.

My endpoint cannot find order_number

Read args.order_number during live execution. A voice configurator sample initially places parameters at the root.

The text test cannot connect

Check the endpoint URL and browser CORS response. The test runs from the browser; real text execution runs on the server.

I need the final transcript inside a tool

A tool runs during the conversation. Receive the completed transcript and analysis through the post-call webhook instead.

Documentación API

Voz

WhatsApp (WABA)

Canales y conversaciones

Organización

Agentes

Contactos

Etiquetas

Llamadas

Tareas

Números de teléfono

Set up an HTTP tool

Post-call webhook

Voice request

Text request

Your endpoint response

Test requests versus live execution

Find the data and diagnose failures

Set up an HTTP tool

Post-call webhook

​Voice request

​Text request

​Your endpoint response

​Test requests versus live execution

​Find the data and diagnose failures

Voice request

Text request

Your endpoint response

Test requests versus live execution

Find the data and diagnose failures