From connection to conversation.From connectionto conversation

1. Request beta access. Once we approve your email, create an account and verify it.
2. Add credit for number rental and SMS.
3. Get a number. Choose a 1, 3 or 12 month initial term and review the quote.

Then choose how to connect. You can also let an authorized agent buy numbers using the quote and purchase tools.

In your client's settings, add a remote HTTP MCP server using this URL. The exact setting name depends on your client.

https://agenttelco.com/mcp

Sign in when prompted, choose the workspace, and review access. Open Connections to choose the numbers this agent can use and whether it can buy or manage numbers.

A hosted agent that cannot open a browser to sign in can use the same URL with an API key. Send it as Authorization: Bearer YOUR_API_KEY. The key's permissions and numbers apply to every tool.

Start with this prompt. It only asks the agent to read your connection and numbers.

Use Agent Telco to check my account with get_account and list my numbers with list_numbers. Tell me which numbers this connection can use and whether it can send SMS.

To test the connection, open Connections, choose the agent and number, and start an SMS test. Send the supplied code to your own phone, reply with that code, and ask the agent to read it.

Create an API key with the permissions your application needs. Use a separate key for each agent. Store it in an environment variable or secret manager, outside prompts and source code.

# Set AGENTTELCO_API_KEY in your environment first.
export AGENTTELCO_BASE_URL="https://agenttelco.com"

curl "$AGENTTELCO_BASE_URL/api/v1/account" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY"

data contains your available credit, number access, and capabilities. If an action is blocked, read its blockers for the next step. number_id is a resource ID; from and to are telephone numbers in international format.

List your numbers first. You may already have an active sender.

curl "$AGENTTELCO_BASE_URL/api/v1/numbers" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY"

For another number, request a quote. Review its upfront charge, monthly renewal and billing date. Save data.id, then use that quote ID to purchase.

curl -X POST "$AGENTTELCO_BASE_URL/api/v1/number-quotes" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"initial_months":1,"auto_renew":true}'

# Replace ACCEPTED_QUOTE_ID with the quote's data.id.
curl -X POST "$AGENTTELCO_BASE_URL/api/v1/numbers" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"quote_id":"ACCEPTED_QUOTE_ID"}'

With MCP: call quote_number with initial_months and auto_renew, then purchase_number with the accepted quote_id.

One quote buys one number. Reuse the same quote ID after a timeout. If the result is pending, follow meta.location to check the existing order. An agent with selected-number access receives access to the numbers it purchases; other agents keep their own permissions.

Choose an active sender from your number list. Replace both example numbers below with your Agent Telco number and a phone you can receive the test on. If you have several numbers, choose the sender explicitly.

curl -X POST "$AGENTTELCO_BASE_URL/api/v1/messages" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-sms-001" \
  --data '{
    "from": "+441632960128",
    "to": "+447700900456",
    "body": "Hello from my agent. Please reply to this message."
  }'

With MCP: use send_message with from, to, body and idempotency_key. Use a new key for each intended message; keep the same key and content for retries.

Save the returned message ID. segments reports message length in billable SMS segments; billing reports the reserved or charged amount when available. Accepted does not mean delivered. Call get_message or GET /api/v1/messages/MESSAGE_ID to check delivery status.

With MCP: call receive_messages. It reads inbound messages oldest first, then waits up to 25 seconds. Save meta.resume_cursor and pass it as after on the next call. Optionally set number_id to follow one number.

With the API: callGET /api/v1/messages/receive. Save the returnedmeta.resume_cursor and pass it as afterto continue. Use GET /api/v1/messages withcursor separately to browse older history.

curl "$AGENTTELCO_BASE_URL/api/v1/messages/receive" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY"

# Save meta.resume_cursor, then use it as after.
curl "$AGENTTELCO_BASE_URL/api/v1/messages/receive?after=RESUME_CURSOR&wait_seconds=25" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY"

Keep the same filters when continuing a cursor. Empty timeouts are successful. Save the cursor even when the page is empty. This feed follows new messages; use a message's ID or message.updated webhooks for changes to delivery status.

Register an HTTPS endpoint with a key that has webhooks:write. Choose message.received for incoming SMS and message.updated for delivery updates.

curl -X POST "$AGENTTELCO_BASE_URL/api/v1/webhooks/endpoints" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-webhook-001" \
  --data '{
    "name": "My hosted agent",
    "url": "https://your-app.example/webhooks/agenttelco",
    "event_types": ["message.received", "message.updated"]
  }'

Save the returned signing secret in your application's secret manager. Omit number_ids for all numbers this connection can access, or supply an array of number IDs to narrow delivery. Removed permissions also stop queued deliveries.

• Verify X-AgentTelco-Signature as v1= followed by the hexadecimal HMAC-SHA256 of the timestamp, a period, and the unchanged request body.
• Use X-AgentTelco-Timestamp, reject stale timestamps and compare signatures in constant time.
• Persist X-AgentTelco-Event-Id and ignore duplicates. Delivery can happen more than once.

How delivery works:

• Answer with any 2xx within 10 seconds. Do slow work after you respond. Redirects are not followed.
• Anything else is retried 8 times over about 24 hours: after 15 seconds, 2 minutes, 15 minutes, then 1, 2, 4, 6 and 10 hours. Answer 410 to stop retries for an event.
• Events can arrive out of order. Use created_at and the message status rather than arrival order.
• When deliveries keep failing we email the workspace owners, at most once a day for each webhook.
• Delivery history is kept for 30 days.

Open a webhook in the console to see every event, each attempt and what your endpoint answered, and to retry an event that failed. Send test event posts a signed webhook.test event so you can check your endpoint and signature verification without sending an SMS. It is also available as POST /api/v1/webhooks/endpoints/ENDPOINT_ID/test.

Use GET /api/v1/webhooks/deliveries to list deliveries. Delivery details and replay are documented in the OpenAPI reference.

Auto-renew uses workspace credit after the initial term. Renewals are monthly at the original term's rate. Keep enough credit available at least 15 minutes before the billing time; numbers with insufficient credit or auto-renew turned off are disconnected during that window.

curl -X PATCH "$AGENTTELCO_BASE_URL/api/v1/numbers/NUMBER_ID" \
  -H "Authorization: Bearer $AGENTTELCO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"auto_renew":false}'

With MCP: use update_number with number_id and auto_renew. Changes are locked during the renewal decision window. You can also manage renewals on the Credit page.

To disconnect immediately, use release_number or DELETE /api/v1/numbers/NUMBER_ID. Sending and receiving stop. There is no automatic refund for unused rental.

REST and MCP use the same response shape: data for the result, optional meta for paging or pending work, and error when a call fails.

• Read error.code and error.message. When present, action_url points to a page that can help resolve the issue.
• For a retryable error, respect retry_after_seconds. Retrying a write always uses its original quote ID or idempotency key.
• For an unknown SMS submission or number order, check the existing resource. Do not create a replacement request.
• HTTP 202 means work is still pending. It does not confirm a completed purchase or delivery.