Connect CallHub to ChatGPT: Manage Contacts and Campaign Workflows

If you need to connect CallHub to ChatGPT to automate voice broadcasting workflows, manage complex SMS campaign lifecycles, or orchestrate high-volume contact phonebooks, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's JSON-based tool calls and CallHub's specialized telephony REST APIs.

If your team uses Claude, check out our guide on connecting CallHub to Claude or explore our broader architectural overview on connecting CallHub to AI Agents.

Giving a Large Language Model (LLM) read and write access to a telephony and campaign management platform is an engineering challenge. You have to handle strict regulatory compliance endpoints (like Do-Not-Call registries), manage asynchronous bulk contact uploads, and navigate complex status flags for live campaigns. Every time you want to expose a new CallHub endpoint to your AI, custom server code must be updated, redeployed, and tested.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for CallHub, connect it natively to ChatGPT, and execute complex campaign workflows using natural language.

The Engineering Reality of the CallHub API

Building an MCP server is essentially building a self-hosted integration layer. While the MCP standard provides a predictable JSON-RPC 2.0 interface for models to discover tools, implementing it against CallHub's API introduces domain-specific hurdles.

If you decide to build a custom MCP server for CallHub, you own the entire API lifecycle. Here are the specific integration challenges you will face:

Telephony Rate Limits and HTTP 429 Handling

Telephony APIs are heavily rate-limited to prevent abuse and manage carrier throughput. When an LLM executes a loop to update fifty contacts, it will almost certainly hit CallHub's rate limits. CallHub returns an HTTP 429 Too Many Requests response.

Factual note on rate limits: Truto does not automatically retry, throttle, or apply backoff on rate limit errors. When the upstream CallHub API returns an HTTP 429, Truto passes that error directly back to the caller. However, Truto does normalize the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF spec. The caller (your AI agent or custom MCP client) is entirely responsible for reading these headers and implementing its own retry and backoff logic.

PATCH Semantics and Campaign Status Flags

When an LLM attempts to pause a Peer-to-Peer (P2P) campaign, standard boolean assumptions fail. CallHub's update_a_call_hub_p_2_p_campaign_by_id endpoint relies on strict integer status flags (1 = START, 2 = PAUSE, 4 = END). Furthermore, the API enforces workflow rules: you cannot change the name of a campaign while its status is set to 1 (Running). Your MCP tool schemas must strictly define these enumerations and their constraints, otherwise ChatGPT will hallucinate invalid state transitions, resulting in HTTP 400 Bad Request errors.

Asynchronous Bulk Imports

LLMs operate synchronously by default - they call a tool and wait for the response to continue reasoning. However, CallHub's phonebook ingestion is asynchronous. When you call the create_a_call_hub_contacts_bulk_create endpoint with a CSV URL, CallHub accepts the request and processes imports in the background. The LLM receives a generic openapi or info object back, not the created contacts. If your system prompts the LLM to verify the contacts immediately after upload, the agent will fail because the downstream database has not yet reconciled the records.

Step 1: Generating the CallHub MCP Server

Instead of building and hosting a custom JSON-RPC server, you can use Truto to dynamically generate an MCP server mapped directly to your connected CallHub account. Truto derives the tool definitions directly from the integration's documented API schema.

You can generate this server via the Truto dashboard or programmatically via the API.

Method 1: Via the Truto UI

1. Log into your Truto account and navigate to Integrated Accounts.
2. Select your connected CallHub account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can filter the server to only expose specific methods (e.g., read only) or specific resource tags (e.g., campaigns, contacts).
6. Click Generate and copy the resulting MCP server URL.

Method 2: Via the Truto API

For teams embedding AI into their own infrastructure, you can provision MCP servers on the fly. This single POST request scopes an MCP endpoint to a specific CallHub tenant.

curl -X POST https://api.truto.one/integrated-account/$INTEGRATED_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CallHub Campaign Manager",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["campaigns", "contacts", "teams"]
    }
  }'

The response returns a secure, authenticated URL:

{
  "id": "abc-123",
  "name": "CallHub Campaign Manager",
  "config": { "methods": ["read", "write", "custom"], "tags": ["campaigns", "contacts", "teams"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

This URL (https://api.truto.one/mcp/...) is a fully compliant JSON-RPC 2.0 endpoint. It contains a cryptographically hashed token that routes requests to the correct CallHub instance. Treat this URL like a secret credential.

Step 2: Connecting the MCP Server to ChatGPT

Once you have the Truto MCP URL, you need to register it with your LLM client.

Method A: Via the ChatGPT UI

If you are using ChatGPT Pro, Plus, Business, Enterprise, or Education, you can connect remote MCP servers directly in the interface.

1. In ChatGPT, click your profile picture and go to Settings.
2. Navigate to Apps -> Advanced settings.
3. Toggle on Developer mode.
4. Under the MCP servers / Custom connectors section, click Add new server.
5. Enter a name (e.g., "CallHub Integration").
6. Paste the Truto MCP URL into the Server URL field.
7. Click Save.

ChatGPT will immediately send an initialize JSON-RPC payload to the URL, handshake with Truto, and pull down the dynamically generated CallHub tool schemas.

Method B: Via Manual Config File (SSE Transport)

If you are building a custom agent using LangChain, LangGraph, or running a local development environment that consumes MCP servers via configuration files (like Cursor or Claude Desktop's approach, which translates well to headless agent configs), you can use the official MCP SSE transport module.

Create an mcp_config.json file for your agent framework:

{
  "mcpServers": {
    "callhub_truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}

When your agent framework boots, it uses the server-sse wrapper to convert standard stdio MCP communication into HTTP POST requests directed at your Truto MCP URL.

Hero Tools for CallHub Workflows

Truto automatically generates descriptive, LLM-friendly snake_case tool names based on the CallHub API documentation. All arguments arrive to Truto as a single flat object, and the internal MCP router splits them into query parameters and body parameters using the underlying OpenAPI schemas.

Here are the highest-leverage tools available for orchestrating CallHub workflows.

create_a_call_hub_dnc_contact

This tool adds a phone number to the Do-Not-Call list, ensuring compliance across your voice and SMS campaigns. It requires the dnc list ID and the phone_number. You can also pass a category (1 for voice opt-out, 2 for text opt-out, 3 for both).

Usage Note: Always execute this tool first when a user requests an opt-out before taking any other action on the contact record.

"The user +15551234567 just texted 'STOP'. Add them to our global DNC list for both voice and text immediately."

update_a_call_hub_p_2_p_campaign_by_id

Controls the execution state of a Peer-to-Peer campaign. This is a PATCH endpoint. You must provide the campaign id and the new status integer (1 = START, 2 = PAUSE, 4 = END).

Usage Note: The LLM must be explicitly prompted about the integer status flags, though the injected JSON schema description will also provide this context.

"We need to halt the 'Q3 Donor Outreach' P2P campaign. Find its ID and change its status to PAUSE (2)."

call_hub_team_agents_bulk_update

Assigns existing CallHub agents to a specific team in bulk. It requires the team_id and an array of agent_ids.

Usage Note: This overwrites or appends depending on the upstream API behavior. It is critical for rapidly scaling up a campaign by allocating a pool of agents to a specific call center team.

"Take agents 402, 405, and 410 and assign them to the 'West Coast Sales' team in CallHub."

list_all_call_hub_credits_usage

Retrieves detailed billing and credit usage over a specific date range. It requires a start_date (formatted mm/dd/yyyy) and returns breakdowns of sms_amount, voice_amount, and credits_remaining.

Usage Note: If end_date is omitted, the tool retrieves usage for a single day based on UTC 00:00-23:59.

"Pull the CallHub credit usage report for 10/15/2023. I need to know how much we spent on SMS versus Voice yesterday."

create_a_call_hub_rent_number

Rents a new localized phone number for use in call center or voice broadcast campaigns. Requires the country_iso.

Usage Note: If you do not specify an area code, CallHub will rent a random available number in the specified country. The tool returns the rented number, capabilities, and associated rental charges.

"We are launching a new campaign in Canada. Rent a new Canadian phone number in CallHub that supports both Voice and SMS."

create_a_call_hub_contacts_bulk_create

Triggers an asynchronous bulk import of contacts into a specific phonebook. You must supply the phonebook_id, mapping details, and a csv_url pointing to the hosted file.

Usage Note: Because this is an asynchronous job, instruct the LLM that the returned response indicates the job has started, not that the contacts are instantly available for querying.

"Import this CSV of new leads (https://example.com/leads.csv) into the 'November Prospecting' phonebook in CallHub."

list_all_call_hub_campaign_info

Fetches high-level metrics for specific campaigns, including status, total contacts, and completed calls. It accepts an array of campaign IDs.

Usage Note: Use this tool to generate daily status reports or to check if a campaign has burned through its assigned phonebook.

"Get the latest campaign info for campaign IDs 8821 and 8822. Tell me the total contact count and how many calls have been completed."

To view the complete inventory of available CallHub tools and their precise JSON schemas, visit the CallHub integration page.

Workflows in Action

Providing individual tools to ChatGPT is useful, but the real power of MCP emerges when the model orchestrates multi-step workflows based on a single natural language prompt. Here are three real-world automation scenarios.

Scenario 1: Immediate Campaign Pause and Compliance Enforcement

During a live voice broadcast, a compliance officer realizes a specific geographic area was mistakenly included. They need to halt the campaign and ensure a specific test number is added to the Do-Not-Call list to prevent further accidents.

"Pause the P2P campaign with ID 9942 immediately. Then, add +15559876543 to the global DNC list for voice only (category 1)."

Execution Steps:

1. ChatGPT calls update_a_call_hub_p_2_p_campaign_by_id, passing {"id": 9942, "status": 2} to halt outbound dialing.
2. ChatGPT calls create_a_call_hub_dnc_contact, passing {"phone_number": "+15559876543", "category": 1}.
3. The agent reads the 201 Created response and informs the user that the campaign is paused and the number is restricted.

sequenceDiagram
    participant User as User
    participant GPT as ChatGPT
    participant MCP as Truto MCP Server
    participant Upstream as CallHub API

    User->>GPT: Pause campaign 9942 & add DNC
    GPT->>MCP: Call tool: update_a_call_hub_p_2_p_campaign_by_id
    MCP->>Upstream: PATCH /v1/p2p_campaign/9942/
    Upstream-->>MCP: 200 OK
    MCP-->>GPT: Return success
    GPT->>MCP: Call tool: create_a_call_hub_dnc_contact
    MCP->>Upstream: POST /v1/dnc/
    Upstream-->>MCP: 201 Created
    MCP-->>GPT: Return success
    GPT-->>User: Campaign paused and DNC updated

Scenario 2: Provisioning a New Market Setup

A campaign manager is spinning up a new market initiative in the UK and needs infrastructure provisioned quickly.

"We are expanding to the UK. Rent a new UK phone number in CallHub. Then, create a new team called 'UK Inbound Sales', and assign agents 501 and 502 to that new team."

Execution Steps:

1. ChatGPT calls create_a_call_hub_rent_number with {"country_iso": "GB"}. It receives the new number and its internal ID.
2. ChatGPT calls create_a_call_hub_team with {"name": "UK Inbound Sales"} and extracts the new team_id from the response.
3. ChatGPT calls call_hub_team_agents_bulk_update passing the new team_id and {"agent_ids": [501, 502]}.
4. The agent summarizes the setup, providing the user with the new UK phone number and confirming the team is ready.

Scenario 3: Auditing Daily Spend and Campaign ROI

A financial controller wants an end-of-day summary of telephony usage compared to the output of active campaigns.

"Pull the CallHub credit usage for today. Once you have the spend, look up the campaign info for active campaigns 4410 and 4411 to show me how many total contacts we reached for that spend."

Execution Steps:

1. ChatGPT determines today's date and calls list_all_call_hub_credits_usage with {"start_date": "10/24/2023"}.
2. The model parses the returned sms_amount and voice_amount metrics.
3. ChatGPT calls list_all_call_hub_campaign_info passing {"id": [4410, 4411]}.
4. The model correlates the total contacts completed from step 3 against the credit drain from step 2, generating a cohesive natural language report for the controller.

Security and Access Control

Because an MCP server URL provides direct access to execute API operations on behalf of the integrated CallHub account, Truto includes several layers of security to constrain the LLM's blast radius.

• Method Filtering: When creating the MCP server, you can pass "methods": ["read"] to entirely exclude write operations (create, update, delete). This ensures a reporting agent cannot accidentally delete a contact or launch a campaign.
• Tag Filtering: You can restrict the server to only expose specific API domains using "tags": ["campaigns"]. If the LLM tries to hallucinate a contact update, the tool simply will not exist in the server's manifest.
• Require API Token Auth: By setting require_api_token_auth: true in the config, possession of the MCP URL is no longer sufficient. The connecting client must also pass a valid Truto API token in the Authorization header, enforcing a second layer of identity verification.
• Expires At: You can pass an ISO datetime to the expires_at field. Once this timestamp is reached, the underlying Key-Value storage automatically evicts the token, and the cleanup alarms destroy the server record. This is perfect for granting temporary access to automated auditing agents.

Moving Forward with Telephony Agents

Connecting ChatGPT to CallHub unlocks massive operational efficiency, but it requires careful handling of API constraints. Telephony rate limits, strict asynchronous workflows, and specific state flags mean that raw HTTP requests are brittle.

By leveraging an auto-generated MCP server through Truto, you abstract away the authentication refresh cycles, schema management, and endpoint routing. Your AI agents interact with a clean, heavily curated list of tools derived directly from CallHub's documentation, allowing your engineering team to focus on prompt design and agent orchestration rather than maintaining brittle API glue code.