Connect DingConnect to AI Agents: Orchestrate Global Airtime Sales

You want to connect DingConnect to an AI agent so your system can autonomously lookup international phone numbers, discover valid telecom products, calculate complex foreign exchange prices, and execute global airtime and data transfers. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom DingConnect integration from scratch.

Giving a Large Language Model (LLM) read and write access to a global telecom API is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that handles complex state polling, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting DingConnect to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting DingConnect to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for DingConnect, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex global remittance workflows. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, decide what layer your agent talks to. This choice determines how safe your production system will be—especially when financial transactions and live airtime top-ups are involved.

Direct API tools (one tool per raw DingConnect endpoint) push provider quirks directly into the LLM's context window. The model has to memorize exact HTTP methods, pagination cursor formats, and strict header requirements. Every one of those quirks is a hallucination waiting to happen.

Routing your agent through a unified tool layer gives you concrete safety wins:

1. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit DingConnect, so a broken tool call fails fast instead of burning funds.
2. Reduced prompt bloat. Truto handles the authentication tokens, base URLs, and normalized pagination out of the box. Your agent only needs to pass business logic parameters, saving tokens and improving reasoning accuracy.
3. Framework agnosticism. Truto’s tools can be consumed by any orchestrator—LangChain, CrewAI, or raw OpenAI function calling. You are not locked into a specific agent architecture.

The Engineering Reality of the DingConnect API

Giving an LLM access to external APIs sounds simple until you hit production. DingConnect's telecom API introduces specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

The Product Discovery Dependency Chain

DingConnect operates on a strict dependency tree. You cannot simply instruct an API to "send $5 to phone number X." The API requires a highly specific SkuCode.

To find a valid SkuCode, an agent must navigate a deep lookup sequence:

1. Query the phone number to identify the region and provider (GetAccountLookups).
2. Query available products for that specific provider and region (GetProducts).
3. Filter those products based on processing modes, minimum/maximum limits, and validity.

If you expose raw endpoints, the LLM often attempts to skip steps, hallucinating SkuCode strings. The tool schemas must strongly enforce this operational chain.

Synchronous Timeouts and ProviderTimedOut States

Global telecom networks are notoriously unreliable. DingConnect enforces a strict 90-second synchronous timeout window for the SendTransfer endpoint. If the downstream telecom provider fails to respond within that window, DingConnect returns a ProviderTimedOut state.

Critically, transfers that exceed 90 seconds are not charged to your agent balance. However, your agent must be explicitly programmed to handle this state, checking the exact ProcessingState returned, rather than assuming a standard HTTP 500 means the transaction definitively failed. Retrying blindly could result in double-charges if the initial request was actually processing.

Fractional Currency and Dual Value Mechanics

DingConnect products rely on dual value structures: SendValue (what you pay) and ReceiveValue (what the customer gets). The API strictly dictates that SendValue and ReceiveValue cannot both be non-zero in the same request. You specify one, and the engine calculates the other based on real-time foreign exchange rates and tax bands. Agents naturally want to specify both, resulting in immediate 400 Bad Request errors.

DingConnect Hero Tools for AI Agents

Instead of exposing the entire raw DingConnect API surface, you provide the agent with a focused set of high-leverage tools mapped to their schemas. Here are the core "hero" tools your agent needs to execute end-to-end airtime sales.

Get Account Lookups

Before doing anything, the agent must identify the telecom provider for a specific phone number. This tool accepts an international phone number and returns the country, provider, and region code details.

"I need to send airtime to +52 55 1234 5678. Look up the account to see which Mexican telecom provider it belongs to."

Get Products

Once the provider is identified, the agent queries this tool to retrieve the catalog of available products. It returns complex objects detailing SkuCode, min/max pricing, and the ProcessingMode.

"List all the available top-up products for Telcel Mexico. I need to find the specific SkuCode for a 100 MXN airtime package."

Estimate Price

Before committing to a transaction, the agent uses this tool to execute a dry-run calculation. It submits the SkuCode and either the SendValue or ReceiveValue, returning the exact customer fees, distributor fees, and tax rates.

"Estimate the price to send the Telcel 100 MXN SkuCode. Tell me exactly what the SendValue will be in USD after taxes and fees."

Send Transfer

The execution tool. It accepts a valid SkuCode, the phone number, and the financial values to trigger the live airtime top-up. The response includes a critical ProcessingState.

"Execute a transfer for the Telcel 100 MXN SkuCode to +52 55 1234 5678. Track the processing state to ensure it succeeds."

List Transfer Records

If a transfer times out or requires asynchronous verification, the agent uses this tool to query historical transfer records. It requires a Take parameter to handle pagination and returns the final ProcessingState and receipt text.

"Check the status of the last 5 transfers I initiated today. Are any of them stuck in a pending state?"

Get Balances

A safety-check tool. The agent queries this to verify your DingConnect distributor balance before attempting large batch transactions.

"Check my current DingConnect balance. Do I have enough funds to process fifty $10 USD equivalent transfers?"

This is just a subset of the available operations. For the full list of supported capabilities, schemas, and configurations, check the DingConnect integration page.

Workflows in Action

When you bind these tools to a reasoning engine, you unlock autonomous workflows that previously required custom microservices and cron jobs.

Scenario 1: Automated Customer Support Compensation

The Prompt:

"Ticket #4928 reports a dropped international call. Compensate the user by sending $5 USD of airtime to their registered number (+91 98765 43210). Confirm when the transfer is successful."

The Agent Execution:

1. The agent calls list_all_ding_connect_get_account_lookups with +919876543210 to identify the Indian telecom provider (e.g., Airtel India).
2. The agent calls list_all_ding_connect_get_products filtering by the returned ProviderCode to find available SKUs.
3. The agent selects a relevant SkuCode and calls create_a_ding_connect_estimate_price with SendValue: 5 to verify the transaction math and exact ReceiveValue in INR.
4. The agent calls create_a_ding_connect_send_transfer to execute the transaction.
5. The agent reads the ProcessingState from the response. It sees Complete and replies to the user via the ticketing system that the airtime has been credited.

Scenario 2: Global Remittance Batch Verification

The Prompt:

"I have a CSV of 20 phone numbers in the Philippines. Before we process the marketing campaign, check if our DingConnect balance can support a 200 PHP top-up for all of them, and verify which numbers are actually active on the Globe network."

The Agent Execution:

1. The agent calls list_all_ding_connect_get_balances to check the current USD balance.
2. The agent iterates through the 20 numbers, calling list_all_ding_connect_get_account_lookups for each.
3. It cross-references the returned ProviderCode to identify which ones belong to 'Globe'.
4. It queries list_all_ding_connect_get_products for Globe to find the SkuCode corresponding to 200 PHP.
5. It runs create_a_ding_connect_estimate_price once to determine the exact USD cost per transaction, multiplies it by the valid Globe numbers, and compares it to the balance.
6. The agent outputs a summarized report detailing the total cost and listing the valid vs invalid numbers.

Building Multi-Step Workflows

To build these multi-step workflows, you need to connect your agent framework to Truto's proxy APIs. Below is an architecture pattern using LangChain in TypeScript, utilizing TrutoToolManager to fetch the DingConnect schemas dynamically.

Handling API Rate Limits

When designing an autonomous agent loop, you must defensively program for rate limits. Truto acts as a transparent proxy for external API traffic. It does not retry, throttle, or apply arbitrary backoff logic on rate limit errors.

When DingConnect returns an HTTP 429, Truto passes that 429 directly to your caller. However, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification: ratelimit-limit, ratelimit-remaining, and ratelimit-reset. Your agent's execution loop or HTTP client must read the ratelimit-reset header and implement exponential backoff.

Implementing the Agent Loop

Here is how you orchestrate the connection using the @trutohq/truto-langchainjs-toolset.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
// Initialize the Truto SDK with your API token and the specific DingConnect account ID
const trutoManager = new TrutoToolManager({
  apiKey: process.env.TRUTO_API_KEY!,
  integratedAccountId: process.env.DINGCONNECT_ACCOUNT_ID!,
});
 
async function runAirtimeAgent(userPrompt: string) {
  // Fetch all configured DingConnect tools dynamically from Truto
  const tools = await trutoManager.getTools();
  
  // Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4-turbo-preview",
    temperature: 0,
  }).bindTools(tools); // Bind the Truto schemas directly to the LLM
 
  // Define the system prompt with strict rules for the telecom dependency chain
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", `You are a global telecom operations agent.
      RULES:
      1. ALWAYS use list_all_ding_connect_get_account_lookups first to find the provider.
      2. ALWAYS use list_all_ding_connect_get_products to find the specific SkuCode.
      3. NEVER specify both SendValue and ReceiveValue in the same request.
      4. Verify balances before executing batch transfers.
    `],
    ["user", "{input}"],
    new MessagesPlaceholder("agent_scratchpad"),
  ]);
 
  // Construct the agent and executor
  const agent = await createOpenAIToolsAgent({ llm, tools, prompt });
  const executor = new AgentExecutor({ agent, tools });
 
  // Execute the workflow
  try {
    const result = await executor.invoke({ input: userPrompt });
    console.log(result.output);
  } catch (error: any) {
    // Implement rate limit handling here. Look for 429s and ratelimit-reset headers.
    if (error.status === 429) {
       const resetTime = error.headers['ratelimit-reset'];
       console.error(`Rate limited by DingConnect. Backoff until: ${resetTime}`);
       // Implement client-side queueing or backoff
    } else {
       console.error("Agent execution failed:", error);
    }
  }
}
 
// Example invocation
runAirtimeAgent("Send 5 USD airtime to +44 7700 900077 and tell me the final state.");

The Execution Flow

When the agent runs, the execution loop follows a strict path from reasoning to API execution back to reasoning.

sequenceDiagram
    participant App as Your App
    participant LLM as LLM Agent (LangChain)
    participant Truto as Truto Tool Manager
    participant DC as Upstream API (DingConnect)

    App->>LLM: "Send $5 to +447700900077"
    LLM->>Truto: Tool Call:<br>list_all_ding_connect_get_account_lookups
    Truto->>DC: GET /api/V1/GetAccountLookups
    DC-->>Truto: JSON { ProviderCode: "EE_UK" }
    Truto-->>LLM: Normalized Tool Response
    
    LLM->>Truto: Tool Call:<br>list_all_ding_connect_get_products
    Truto->>DC: GET /api/V1/GetProducts
    DC-->>Truto: JSON { SkuCode: "EE_5_USD" }
    Truto-->>LLM: Normalized Tool Response

    LLM->>Truto: Tool Call:<br>create_a_ding_connect_send_transfer
    Truto->>DC: POST /api/V1/SendTransfer
    DC-->>Truto: JSON { ProcessingState: "Complete" }
    Truto-->>LLM: Normalized Tool Response
    LLM-->>App: "Transfer successful."

By pushing the tool schemas to the agent via Truto, you guarantee that the LLM understands exactly what DingConnect expects, down to the nested objects and required fields. The agent parses the schema, formulates the correct arguments, and relies on Truto to handle the physical request execution and authentication.

Moving from Proof of Concept to Production

Connecting an AI agent to a telecom API like DingConnect requires shifting your mindset from raw integration code to deterministic tool design.

If you hand an LLM naked REST endpoints and API keys, it will hallucinate parameters, misunderstand foreign exchange requirements, and crash against rate limits. By leveraging a unified integration infrastructure, you collapse the complexity of global airtime sales into a clean, predictable set of function calls. The result is a production-ready agent that can orchestrate global telecom logic without draining your engineering bandwidth.