Sending (click-to-call and SMS)

Your own systems can start a click-to-call (POST /v1/calls) and send an SMS (POST /v1/sms) through the API. Both reach real people, so they are off for every account until your account's administrator switches them on, and every send goes through the same checks as a call or message started in the DialerBee console.

What protects every send

• Your own switch. Click-to-call and SMS are each switched on separately by your administrator. Nobody at DialerBee switches them on for you.
• A key made for sending. Only a sending key holds the scopes calls:originate and messages:send. A sending key always has an IP allow-list (your servers' addresses; a network may be at most /16 for IPv4 or /48 for IPv6, never "everywhere") and its own daily and per-minute caps, shared by every credential of that key. An ordinary key can never be given a sending scope.
• Your account's limits. A daily cap for click-to-calls, a daily cap for SMS, a per-minute cap, an optional daily estimated-spend limit and an optional minimum balance below which sending is refused. The estimated-spend limit counts a fixed estimate per send, not the real price of each call: it is not a ceiling on your bill, which remains the exact figure.
• No endless calls. A call started through the API is ended after 30 minutes by default (set by the platform).
• The same compliance checks as the console. Do-Not-Call lists, calling hours, consent, blocked countries and your balance are checked before anything is dialled or sent. A call is placed only from one of your own verified caller IDs; an SMS is sent from your own sender name.
• Stop all sending. One button stops every API call and SMS of your account at once, and DialerBee can stop API sending platform-wide in an emergency. Reading data is not affected.
• No double sends. Every send needs an Idempotency-Key (a retry with the same key answers the first result and never sends twice) and every SMS its own client_reference.
• Every request is recorded in your API log (Settings > API log), with the key, address and result.

Set it up (account administrator)

1. Open Settings > API clients > API sending in the DialerBee console.
2. Choose what the API may do: tick Click-to-call and/or SMS, then confirm.
3. Set your account's limits: the daily caps, the per-minute cap, and if you want them the daily estimated-spend limit and the minimum balance. Save.
4. Create a sending key: give it a name, tick what it may do, enter your servers' IP addresses (required) and the key's daily and per-minute caps. Copy the key at once: it is shown only once. At least one channel (click-to-call or SMS) must be switched on first. While both are off, creating a sending key (POST /v1/settings/api-sending/clients in the console API) is refused with 409 and the code no_channel_enabled ("Switch click-to-call or SMS on before creating a sending key"); nothing is created. Switch one on in step 2, save, then create the key.
5. Store the key as a secret on your servers and send it only in the Authorization header.
6. To pause everything, press Stop all API sending; press Resume sending to allow it again.

A new account created by self-service sign-up can switch sending on only after DialerBee has approved its outbound calling and messaging.

When someone at DialerBee or a partner opens your account with "Login as", they can stop sending and lower your limits, but they cannot switch sending on, raise a limit, add an address to a sending key or create a new credential for it: only your own administrators can.

The click-to-call and SMS tools are not offered by DialerBee's hosted MCP server for now. An AI assistant asks you to confirm each such action in its own window, but that confirmation is given by the assistant application, not checked by DialerBee, so it cannot prove a person approved the send.

Click-to-call

curl -sS https://app.dialerbee.com/api/v1/calls \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to": "+12125550101", "agent_extension": "3901"}'

The named agent must be signed in and ready; DialerBee holds the agent, dials the customer from one of your verified caller IDs (or the caller_id you name, which must be one of them) and joins the agent when the customer answers. See Calls, leads and messages.

SMS

curl -sS https://app.dialerbee.com/api/v1/sms \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to": "+12125550101", "body": "Your order has shipped.", "client_reference": "order-1042"}'

The answer is 202 with the message's status. The compliance checks run before anything is sent. An SMS is checked as a marketing message that needs explicit consent: even a service text such as "Your order has shipped." is refused with message_refused (no_consent) unless you have recorded the customer's consent in DialerBee.

Errors a send can answer

Nothing is dialled or sent when a send answers an error. Retry only with the same Idempotency-Key.