D. DODI TELECOM
DODI TELECOM · Portal user guide
This guide describes the currently available local portal. Both Sandbox and Live use the simulator. Your role controls available actions; changing a selector does not grant access.
Activation and sign-in
Open the personal activation link in your welcome email. Check your sign-in email, enter a password of at least 12 characters and confirm it. Select Activate my account, then sign in. Links work once and expire at the time stated in your email (48 hours by default). Ask the administrator who invited you to resend an expired or cancelled invitation; a resend invalidates the old link.
If you already have an active DODI account, use your existing password and, when enabled, your authenticator or an unused recovery code to accept additional company access. You do not need a new password. Use Sign out in the top toolbar to end your session.
If you forget your password, select Forgot password on the sign-in page and enter your email. The personal reset link expires at the time shown in the email (30 minutes by default) and works once. Choose a new password and sign in again. Password reset revokes existing sessions and does not remove your MFA requirement.
Settings · Security
Use Settings → Security to change your password with the current password. Other browser sessions are revoked after a successful change. Open Account security from the toolbar or Manage account security in Settings.
To enroll Google Authenticator or another TOTP app, enter your current password and select Set up authenticator. Scan the QR code or enter the manual secret. Enter a current six-digit code and select Confirm authenticator within 10 minutes. Enrollment is not active until confirmation succeeds. The secret is shown only during enrollment.
Save the eight recovery codes before closing their one-time display. Each code works once and can complete sign-in if the authenticator is unavailable. Renew recovery codes invalidates all previous codes. If both the authenticator and recovery codes are lost, select Lost authenticator at sign-in and request identity verification using your current password. Another authorized administrator must verify your identity. Approval sends a personal link valid for 20 minutes; complete it with your password, sign in and enroll a new authenticator before accessing the application. Approval alone does not disable the old factor.
With MFA enabled, sign-in first checks your password, then asks for an authenticator or unused recovery code. Recent identity confirmation is also required for sensitive actions, including credential changes. If confirmation has expired, a dialog requests your authenticator/recovery code (or your password when no second factor is enrolled).
Email verification codes may be enabled only with a verified email and compatible role policy. They are weaker than an authenticator and cannot replace an enabled or required authenticator. Select Send email code when prompted; each code expires after five minutes, works only in the requesting session and works once. Resending invalidates the old code. Attempts and resends are limited.
Active sessions lists your browser sessions. Revoke session ends another session. Disable authenticator requires recent confirmation and your current password; it is unavailable when your role requires TOTP.
Change sign-in email in Account security requires recent identity confirmation and your current password. Verify the code sent to the new address within five minutes. The change ends existing sessions and retains your authenticator; sign in with the new address and your existing factor. Notices go to both addresses.
Owners can open Customer security policy under Members & invitations. Require authenticator, Email codes and Recent confirmation lifetime apply to all active company members. The strictest role/company requirements win; allowing email codes cannot weaken mandatory TOTP. Save security policy records the change and current sessions enforce it.
Settings · My profile, Company and Preferences
Use My profile → Save profile to update your name and personal phone. Sign-in email changes use the verified Account security workflow. Company → Save company updates the selected company’s legal name, address and billing contact; a billing contact is not an invited user.
Preferences → Save preferences applies the company time zone and your personal Date format to displayed timestamps. API responses and exported CSV timestamps stay in UTC. Existing historical instants do not change. English is available; French is a future translation. Your current role must allow Settings.
Members & invitations
Authorized customer owners can use Members & invitations in Settings. Enter the person's name, email and current role, then Invite user. Built-in Member starts with limited read permissions; Owner grants customer administration. Review permissions to see the role's current grants. You cannot grant permissions you do not hold. Each person receives a distinct invitation. Commercial and financial contacts are not users.
The invitation list shows Pending, Expired, Accepted or Cancelled / replaced. Resend invalidates the old link and sends a fresh personal link. Cancel invitation prevents activation. Accepted invitations cannot be reused.
For an activated member, select Edit access to change their role or suspend/revoke membership. Changes take effect on existing sessions. The last active owner cannot be removed. Customer roles → Create role creates a customer-specific role; Review permissions shows its grants and lets authorized editors confirm changes. Shared roles can be changed only by a global internal administrator.
M-PESA and Pay by PayBill
In Wallet or Pay & top up, select M-PESA (STK push) or Pay by PayBill using mouse or keyboard, then Continue. Enter a whole KES amount and, for Express, the payer phone. Choose Review payment, check the company, environment and amount, then submit. Never enter your M-PESA PIN here.
Local Sandbox and Live use the simulator. PayBill displays the fictitious DODI-SIM-PAYBILL, exact amount and server-generated reference with copy buttons. Confirmation is automatic. The late success scenario first shows unknown, then confirms later without another click. No real money is collected.
Payment history refreshes for at most two minutes. Refresh payments resumes waiting. Closing the modal, page or signing out does not cancel server processing. Return to Wallet for the status, updated balance and Download receipt. A duplicate notification cannot credit twice. Unknown results require reconciliation of the original request, not a blind retry.
Internal administrators manage independent Daraja Sandbox and Production profiles. A client environment selector never activates external transport. Real Daraja acceptance is pending; C2B v2, Transaction Status and Pull depend on contracts not currently supplied.
Wallet and top-ups
Wallet shows posted balance, reserved amount and available funds. Under Request a top-up, enter the amount and Payment reference. Optionally select Proof of payment (PDF, JPG or PNG, up to 5 MB) and wait for the filename before submitting. Each uploaded proof can be attached to one request; unattached uploads expire after 24 hours. A separate authorized internal approver must approve the request before it credits the ledger. The proof is evidence for review, not confirmation of payment. Payment processing is simulated; no external payment is collected.
Reservations reduce available funds while SMS operations are in progress. An uncertain submission retains its reservation for investigation; it is not automatically refunded. Attached proofs are private and available to their uploader and currently authorized scoped financial reviewers. Export statement queues a private CSV.
In My top-up requests, select Review / respond to read Finance comments and review history. If the request is awaiting information, enter Response to Finance and select Submit information. This returns the request for review and does not credit your wallet. Internal review notes are visible only to authorized Finance users. Rejected requests retain the visible reason; a different reviewer must approve a pending request before any credit is posted.
M-PESA PayBill is available from Wallet, Pay & top up and Finance in the local simulator. Choose M-PESA Express / STK Push or Manual PayBill / C2B, enter a whole KES amount, and select a local simulator outcome. STK also asks for a Kenyan phone number; never enter your M-PESA PIN. No real prompt or payment is sent, including in Live.
Create PayBill reference shows the non-routable DODI-SIM-PAYBILL and a personal payment reference. Simulate PayBill payment records provider evidence locally. Submission acceptance is not payment. If the result is unknown, reconcile the same request; Simulate late confirmation demonstrates this locally. Never pay again blindly. Finance reviews incorrect amounts or references. Download receipt is available only after the wallet credit. Simulator credit equals the confirmed KES amount; no exchange rate or payment fee is invented.
Sender IDs
Open Sender IDs to request an alphanumeric Sender ID. It remains pending until an authorized internal reviewer approves and maps it to the local simulator. Use an approved Sender ID for sending. Existing statuses are read from the backend.
Estimation and Send SMS
Select the correct environment and open Send SMS. Choose the approved Sender ID and recipient type, then enter the exact recipient and message. The local form uses the configured KE-Safaricom simulator destination. Hash recipients are opaque identifiers: preserve whitespace, case and namespace as supplied by your integration. Select Review & send to inspect the server estimate before confirming Send message. The estimate itself sends no SMS.
Confirm submission only when you intend to send. A successful admission returns a message UUID; retain it for tracking. The local batch API accepts at most 100 messages atomically. An estimate does not reserve funds, while admission does. SMS charges follow the snapshotted acceptance or delivery policy.
Messages and statuses
Messages lets you filter by time, Sender ID, recipient type and status, and inspect message details. Recipient search is exact and scoped to the customer and environment. Queued means admitted; Accepted means accepted by the simulated provider; Delivered or Failed reflect delivery events. Submission uncertain means provider acceptance could not be established.
Do not resend an uncertain message merely to clear its status. Delivery receipts and financial effects are reconciled against the original operation. Repeated receipts do not create repeated charges.
API Credentials
Open API Credentials and create a credential with its authentication method, environment and permitted operations. Apply expiry and IP restrictions when appropriate. Five methods are supported: API key — Bearer header, API key — custom header, Client ID + API key, OAuth2 client credentials, and Basic auth (username / password).
Save the generated secret securely during its one-time display. It cannot be retrieved again after the dialog closes. Pending credentials generate the secret when retrieved. Rotation replaces the secret and revokes the old generation immediately, including issued OAuth tokens. Revocation stops further use. Credentials never belong in email, URLs, screenshots or support messages.
API Playground
Select the same environment and method as your credential. Enter the credential fields and click Connect. For OAuth2 client credentials, first obtain a temporary access token from the token endpoint using the API documentation, then use that token in the Playground.
Begin with a permitted operation that sends no SMS, such as reading the balance or estimating a message. Start in Sandbox when available. A connected identity displays the customer UUID and environment verified by the API; this may differ from your browser's customer context.
Changing environment or authentication method clears secrets and previous results. The local Playground uses only simulator endpoints. No Live send is required for setup. After submitting a simulated message, open DLR & webhooks and select Refresh webhook history to read persisted delivery attempts. This refresh does not send another SMS.
Webhooks
Open Webhooks and keep the configured Local receiver URL. Select message.delivered, message.failed and/or message.expired, then Save configuration. These choices apply to new matching terminal-status notifications in the selected environment. Unchecking all events stops new automatic notifications; deliveries already queued keep their recorded policy. External endpoints remain disabled locally.
Regenerate immediately invalidates the previous signing key and displays a new personal endpoint secret once. Store it securely, then select I stored the secret — hide. The controlled local receiver is updated automatically. Switching environment, saving or reloading clears the displayed key. A signing key is distinct from an API credential and is never included in email.
Send test queues an endpoint.test notification without creating or sending an SMS. The result initially shows Queued; it changes only when persisted delivery history changes. Notification history lets you open the actual event payload, response, handler elapsed time, signing generation and retry schedule. Previous page and Next page navigate older deliveries.
Notifications use HMAC-SHA256 over timestamp and raw body. Verify the signature and freshness, and deduplicate event IDs as described in API documentation. Each delivery records its own attempt limit (at most five), timeout and exponential backoff. Interrupted or timed-out attempts retain an uncertain history. Retry now is available while the recorded budget remains; it re-delivers only the notification, never the SMS. A later acknowledgement does not erase a previous uncertain attempt or promise exactly-once transport.
Reports and exports
Reports shows usage from persisted messages for the selected company and environment. Set filters before selecting Export report. The export runs in the background. Open Private exports in the toolbar to see your request, status, row count and expiry. Select Refresh or wait for the list to refresh, then Download CSV when ready. Wallet → Export statement follows the same workflow for transactions.
Exports require current report access at request time, generation and download. A removed role or customer assignment can prevent download even when the file was previously ready. An empty export is valid and contains the header row. Downloads expire after the lifetime recorded when requested (24 hours by default, measured from generation); expired files are purged while request history remains. CSV timestamps are UTC. Spreadsheet formula characters are escaped without changing API recipient bytes.
Exports include matching records admitted before the request, with their status observed during generation; they are not a frozen financial-period snapshot. The local limit is 100,000 rows or 50 MB per export, and five simultaneous requests per user. Narrow filters if the job reports row limit or size limit. An interrupted worker can recover within the bounded three-attempt budget. Financial ledger records remain immutable.
Notifications
Open Notifications in the toolbar or the bell on Dashboard. Unread marks a new notice; Mark as read records your read state. Open resource goes to the relevant module in the recorded company and environment. Notices and destination actions require your current permissions; losing access can hide older business notices.
Open Preferences to choose In app and Email by category. Optional business emails are off until enabled. Security choices are required and cannot be disabled. Save notification preferences records your choices. Operations preferences apply to authorized internal operators globally; other choices apply to the selected company. Settings → Notifications also saves Low balance alert and Webhook delivery failures; All notification preferences opens the complete matrix.
Set Low balance threshold (KES) above zero to enable threshold checks; zero disables them. At most one low-balance alert per wallet/hour is produced. Invitations, top-ups, Sender ID reviews, ready exports and webhook failures produce authorized notices. Account and credential security changes have mandatory alerts; successful sign-ins are recorded in the center. All local email is captured by Mailpit. No notice contains an API credential or authenticator code.
Assistance and planned modules
Use the support coordinates configured in your welcome email. If none are configured, contact the account administrator who invited you. Include a request ID or message UUID and environment; never include passwords or API secrets.
API documentation is available from Documentation & OpenAPI and the public documentation link below. Real provider transport, external payments, SMPP, passkeys/SSO, campaigns, contact lists and message templates are future modules. This guide is updated when a function is delivered, not when a prototype button exists.