Your first SMS

1. Prepare your organization

Your organization needs an active SMS installation and available credits. Create an organization key with sms.send and delivery.read in BEFIANA Cloud.

Setting up access for the first time? Follow Getting started, then create an API key. The Authentication guide explains the Bearer format and the permissions to select.

The following commands target a Bash terminal. Replace the demonstration number with an authorized recipient. Running them can send a real SMS and consume credits.

export BEFIANA_SMS_API_KEY='bf_sms_REPLACE_WITH_YOUR_KEY'

2. Create the message

Replace the example value order-2026-0001-confirmation with an identifier unique to your operation. Keep it for every retry, with the same body. A deliberate new send uses another key; changing the recipient or text with an already used key causes a conflict. Never change the key to bypass an error or an uncertain outcome.

curl --include --request POST 'https://api.befiana.cloud/api/sms/v2/messages/' \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-0001-confirmation' \
  --data '{"to":"+261340000000","text":"Hello from BEFIANA."}'

--include displays HTTP headers alongside the body. An accepted immediate submission returns 201 and a Location address relative to https://api.befiana.cloud. Example response, with illustrative identifiers and timestamps:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/sms/v2/messages/12f27a77-9666-472d-a34f-90e89371dcd5/

{
  "id": "12f27a77-9666-472d-a34f-90e89371dcd5",
  "to": "+261340000000",
  "sender_name": "BEFIANA",
  "segments": 1,
  "status": "accepted",
  "send_at": null,
  "delivery_time": null
}

Save id and your idempotency key. accepted confirms provider acceptance, not delivery to the handset. segments indicates the message segment count; send_at is null for an immediate message.

The example assumes the resolved sender is BEFIANA. Without sender_name, the service may use your organization’s default sender: do not require this example value in your integration checks.

If the connection drops, retry the same body with the same idempotency key. A retry replays the original creation response; it does not replace a current status lookup. After erasure of the message’s personal data, 410 personal_data_erased stops retries: retain the key without resending. See idempotency.

3. Retrieve the current status

Replace MESSAGE_ID with the returned identifier.

export MESSAGE_ID='REPLACE_WITH_RETURNED_UUID'
curl "https://api.befiana.cloud/api/sms/v2/messages/$MESSAGE_ID/" \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY"

The HTTP 200 response uses the same fields. Here is an example after a delivery receipt has arrived:

{
  "id": "12f27a77-9666-472d-a34f-90e89371dcd5",
  "to": "+261340000000",
  "sender_name": "BEFIANA",
  "segments": 1,
  "status": "delivered",
  "send_at": null,
  "delivery_time": "2030-01-15T06:00:12Z"
}

Looking up the message before that receipt may still return accepted. Do not assume a fixed delay. Read message statuses to handle failures and unknown outcomes without creating duplicates.

If your first request does not succeed

Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.

Response	First check
401 invalid_api_key	Check the complete key, its active state and the Bearer prefix in Authentication.
403	Read error.code: check key permissions, SMS activation or the sender name according to the returned code.
409	Distinguish insufficient_credits (resolve credits), idempotency_in_progress (wait) and idempotency_conflict (find the original body). Do not automatically change the key.
502 provider_result_unknown	Keep message_id and read its status using the GET above. Do not repeat the POST. Without a usable identifier, ask support to investigate.

The SMS error catalogue gives the action for each code. If the problem persists, prepare a support request with the time, code and public identifier, without your API key.

Choose your next step

• Send immediately with your own sender name.
• Schedule one message or a batch.
• Apply an integration recipe and handle retries.
• Read the API reference for all fields and responses.

The portal reference remains read-only: it asks for no key and makes no production request.