Dbrij Ping Documentation

Ping sends text messages to every Nigerian network from your own code or from the dashboard: one time codes, alerts, reminders and campaigns. It is billed in units you buy in advance, and once your business is verified it works under a shared Dbrij sender name while your own name is being approved.

Three things are worth knowing before you build.

• You are charged when a message is sent, not when it is delivered. The networks charge for every message handed to them, whatever happens next, so Ping does too. A message that never left Dbrij is not charged. Keep your lists clean: a dead number costs the same as a live one.
• You say what a message is, and Ping chooses the route. A one time code always takes the route that reaches phones with Do Not Disturb on. You never pick a route yourself.
• Sender names are approved by each network separately, and it takes weeks. Until a network approves yours, its recipients see the shared name, or are skipped if you prefer.

Create an API key in Developer, API keys with the sms:send and sms:read scopes, buy units in Ping, Units, and accept the acceptable use terms in Ping, Settings. Then:

curl https://api.dbrij.com/api/v1/ping/messages \
  -H "Authorization: Bearer <keyId>:<secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-receipt" \
  -d '{ "to": ["08031234567"], "type": "transactional", "body": "Your payment of N25,000 was received." }'

The response carries a Dbrij message id. Keep it: it is how you look the message up, and it is what your webhook is told about. The message is queued at this point. It becomes submitted within seconds, and delivered when the phone receives it.

Every send says what the message is with type. Ping decides the route from that and from what the sender name is registered for. You cannot choose a route directly, on purpose: the wrong one gets messages blocked and gets sender names banned by the networks.

A sender name is registered as transactional or promotional and can only carry its own kind. Sending promotional under a transactional name, or a code under a promotional one, is refused with a 400 that says which name to use instead.

Parts. Plain text is 160 characters a part. One character outside the basic set, including ; ^ { } [ ] ~ | \ and quote marks, or any emoji, makes the whole message 70 a part. The count is fixed when you send and is returned as parts.

• 201 the message is queued and its units are held.
• 402 ping_units_required not enough units. The body carries needed and available. Nothing was queued.
• 429 ping_rate_limited more messages, or more different numbers, in a minute than this workspace allows. Large sends belong in a campaign, which paces itself.
• 403 ping_verification_required the send would go out under a shared Dbrij sender name and the account has not been verified yet. Get verified once under Sender names in the dashboard, and you are given one shared name. That is the only shared name the account can send under, and the only one GET /ping/sender-ids lists. Sends under a sender name of your own that a network has approved are not affected.
• 403 the workspace is suspended, has not accepted the terms, or the number is outside Nigeria while international sending is off.
• 400 a malformed number, a message over 6 parts, a kind the sender name cannot carry, or marketing wording on the transactional route.
• 503 sending is briefly paused on our side. Nothing was charged. Retry with the same Idempotency-Key.

More than 20 recipients in one call becomes a campaign: you get a campaignId back, and the messages are sent in paced batches.

When a message did not arrive, reason says why in plain words. A final status never changes again, with one exception: unconfirmed becomes the real answer if the network reports late.

Each network approves a name on its own, so networks has four answers. For a recipient on a network that has not approved your name yet, Ping follows your workspace setting: send under the shared Dbrij name (the default), or skip. A skipped message comes back with status skipped and costs nothing.

A transactional name takes about 20 working days from the day the letters reach the networks; a promotional one about 2. Register early. It costs nothing to have a name waiting.

Add an endpoint under Developer, Webhooks. Every delivery is signed with that app's own Dbrij secret: X-Dbrij-Signature: sha256=… is an HMAC SHA256 of the raw body, and X-Dbrij-Signature-V2 adds a timestamp so a replayed delivery can be refused. Verify one before you trust the payload.

{ "id", "to", "status": "submitted", "parts", "units", "senderId" }

{ "id", "to", "status": "delivered", … }

{ "id", "to", "status", "reason", … }

The id is always the Dbrij message id you were given when you sent it. Match on that.

• Units. Bought in advance in the dashboard, from your Dbrij wallet or by card. They never expire. There is no credit and no post paid billing.
• Charged at sending. Units are held when a message is accepted and taken when it is handed to the network. There is no refund for a message that did not arrive, because the networks charge for it either way.
• New workspaces send to 5 numbers at a time until their first purchase and the terms are accepted.
• Speed. 120 messages and 60 different numbers a minute by default on direct sends. Campaigns are paced separately and are not bound by this. Ask us to raise it for genuine traffic.
• International sending is off by default and switched on by Dbrij on request.
• Idempotency. Send an Idempotency-Key header on every request you might retry. The same key returns the same message.
• Errors use the platform envelope: { "success": false, "statusCode", "message", "code" }. The message is written to be shown to a person.