Documentation

Getting started

• Create your account and add credit via PIX or USDT.
• In the dashboard, under API / SMPP Connections, register your servers' IPs. Only those addresses can use the API and SMPP.
• Generate your credentials: the API token and the SMPP username and password. They are shown only once; keep them somewhere safe.
• See your SIDs (senders) in the dashboard or through GET /api/v1/routes.

Authentication

Every call uses HTTPS and the token in the Authorization header:

Authorization: Bearer TOKEN
Content-Type: application/json

The API base address is shown in the dashboard, together with your credentials.

SMS API

Sends a message.

curl -X POST https://[API]/api/v1/messages \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sid":"SID","to":"5511999990000","text":"Your code is 482913","reference":"pedido-1001"}'

Response:

{ "id": "dx1234567", "status": "queued", "amount": 45000, "currency": "BRL" }

The amount field is the charge in millionths of the currency (45000 = BRL 0.045).

Returns the status of a message.

{ "id": "dx1234567", "status": "delivered", "phone": "5511999990000", "channel": "sms",
  "created_at": "…", "updated_at": "…", "delivered_at": "…" }

Lists the active SIDs on your account, with channel (sms or rcs), country, price and currency.

Shows the available balance, the balance reserved for sends in progress and the account currency.

RCS

With an RCS SID enabled on your account, use the same send endpoint with "channel": "rcs":

{"sid":"SID_RCS","to":"5511999990000","text":"Your order is out for delivery!","channel":"rcs"}

The message arrives with your brand's name, logo and verification badge. Cards, carousels and buttons, and your brand agent registration, are covered in the RCS guide inside the dashboard.

Webhooks

Register an HTTPS URL of your system in the dashboard to receive message status updates without polling the API.

• Each call is signed with HMAC-SHA256 in the X-DiamondX-Signature header, using the secret shown in the dashboard. Validate the signature before processing.
• Reply with HTTP 2xx. If your system is down, Diamond X retries.
• Use the id or your reference to match the event to the send.

SMPP

• SMPP 3.4, with transmitter, receiver or transceiver binds.
• Up to 3 connections per account, each with its own username and password.
• Delivery reports (DLR) via deliver_sm whenever requested in registered_delivery.
• Long messages: send the parts with UDH or SAR; they arrive together on the handset.
• Access allowed only from the IPs registered in the dashboard.
• Host, port, username (system_id) and password are shown in the dashboard, under API / SMPP Connections, after you sign in.

Errors

Errors return the HTTP status code and a message in the error field.

Questions about the integration? Talk to technical support: WhatsApp · site@diamondx.app