Africastalking Laravel Laravel Package

Getting Started

This package wraps the Africa's Talking REST API (SMS, USSD, voice, airtime, mobile payments) for Laravel. Note you're installing a pre-release (v3.0.0-alpha4) — pin an exact version and expect breaking changes between alphas.

1. Install and scaffold

   composer require samuelmwangi-w/africastalking-laravel
   php artisan vendor:publish --tag=africastalking-config
   

2. Configure credentials in .env:

   AFRICASTALKING_USERNAME=sandbox
   AFRICASTALKING_API_KEY=your-key
   AFRICASTALKING_FROM=MyApp
   

   Start against sandbox username, then swap to your production username/key.
3. First use case — send an SMS using the facade:

   use SamuelMwangiW\Africastalking\Facades\AfricasTalking;
   
   AfricasTalking::sms()
       ->to('+2547XXXXXXXX')
       ->message('Hello from Laravel')
       ->send();
   

4. Where to look first: the config file (for webhook routes, default sender, callback URLs), then the Events/ directory — that's where inbound SMS, USSD sessions, voice callbacks, and delivery/download events (including this release's CallRecordingDownloaded) are surfaced to your app.

Implementation Patterns

• Notifications channel — the idiomatic Laravel path for SMS. Add toAfricastalking() to your notifiable and route via the provided channel:

  public function toAfricastalking($notifiable): AfricasTalkingMessage
  {
      return AfricasTalkingMessage::create()->to($notifiable->phone)->content('...');
  }
  

• USSD flows — handle sessions by responding to the package's USSD webhook event/controller and returning a formatted CON/END response. Keep session state in cache keyed by sessionId so each turn is stateless.

• Voice / call recordings — webhook events fire on call state changes. This release (alpha4) adds fileSize to the CallRecordingDownloaded event payload, so you can persist and gate downloads by size without a HEAD request:

  Event::listen(function (CallRecordingDownloaded $event) {
      // $event->fileSize now available
  });
  

• Payments — use AfricasTalking::payments() for mobileCheckout (C2B), mobileB2C/mobileB2B (payouts). Always pass the correct currency (KES, UGX, TZS, etc.) and a unique metadata reference for reconciliation.

• Testing — the package supports faking HTTP or its own client; combine with Http::fake() or the package's fake helpers to assert outgoing SMS/payment calls without hitting the API. Wrap webhook event tests around Event::fake().

• Idempotency — for inbound webhooks, store a processed-message-id / transaction-id to dedupe retries before dispatching jobs.

Gotchas and Tips

• Alpha instability. Between alpha3 and alpha4 only the event payload changed (additive, non-breaking), but treat every alpha bump as potentially breaking — pin versions and read the changelog each time. The new fileSize property is additive, so existing listeners keep working.
• Phone number format. Always use E.164 (+254...). Bare 07... numbers commonly fail or route incorrectly.
• Webhook security. Africa's Talking does not sign payloads the way Stripe does. Restrict inbound webhook routes to AT's published IP ranges (or a shared-secret callback path) — don't expose them openly.
• Sandbox quirks. The sandbox simulates delivery and can't reach real handsets; USSD/voice behaviour differs. Test the full webhook round-trip on a staging app pointed at a real shortcode.
• Async by default for scale. Sending SMS inline in a request will slow responses and hit rate limits — dispatch through queued jobs; the package's notification channel queues well with ShouldQueue.
• Delivery reports ≠ send success. A successful send() only means AT accepted the message. Listen for the delivery-report event before marking messages delivered in your DB.
• Payments callbacks are the source of truth. Don't trust the synchronous checkout response to confirm payment; reconcile against the callback webhook and the transactionId.
• Callback URL config. Set AFRICASTALKING_*_CALLBACK/config values explicitly — defaults may not match your domain, and AT needs publicly reachable HTTPS URLs.
• Extension point: if you need fields not yet in an event (as fileSize once was), the events are plain classes — add typed accessors or map to your own DTO before persisting.