README

Yii2 extension for integrating with JumbeFupi SMS Gateway

Requirements

You need to register your account at JumbeFupi if you want to send messages to your users or customers. Sign up is FREE.

The JumbeFupi Gateway API credentials required (username, API key and senderID) will be available under the Developer page in your control panel.

Installation

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist danvick/yii2-jumbefupi "*"

or add

"danvick/yii2-jumbefupi": "*"

to the require section of your composer.json file.

To always use the latest version from Github, in your composer.json, add this repository to the repositories section.

{
  ...
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/danvick/yii2-jumbefupi"
    }
  ],
}

Usage

The extension is used as an application component and configured in the application configuration as such:

'components' => [
    ...
    'jumbefupi' => [
        'class' => JumbefupiGateway::class,
        'gatewayUsername' => 'jaribujf',                    // REQUIRED - your JumbeFupi username
        'gatewayApiKey' => 'Jum83fUp14pI_kEy',              // REQUIRED - your JumbeFupi API key
        'senderId' => 'JumbeFupi',                          // REQUIRED - your SenderID / Alphanumeric. If not set here, should be set when sending message
        'callbackUrl' => null,                              // OPTIONAL - the URL where message status response from JumbeFupi Gateway will be sent
        'model' => 'danvick\jumbefupi\models\SmsMessage',   // OPTIONAL - (default: danvick\jumbefupi\models\SmsMessage)
        'db' => 'db',                                       // OPTIONAL - the DB connection component for the messages table
        'cacheBalance' => false,                            // OPTIONAL - whether to store balance after enquiry - cache will be burst on message sending
        'cache' => 'cache',                                 // OPTIONAL - the cache component to store balance if cacheBalance is true 
        'balanceCacheKey' => 'JUMBEFUPI_BALANCE',           // OPTIONAL - cache key for storage of JumbeFupi account balance
        'useFileTransport' => false,                        // OPTIONAL - useful in local development
        'fileTransportPath' => '@runtime/messages'          // OPTIONAL - required if `useFileTransport` is true
    ],
]

You also should configure the extension migrations to be run in your application config by adding danvick\jumbefupi\migrations to your migrationNamespaces:

'controllerMap' => [
    'migrate' => [
        'class' => 'yii\console\controllers\MigrateController',
        ...
        'migrationNamespaces' => [
            ...
            'danvick\jumbefupi\migrations'
        ],
    ],
],

Sending a message

Note: yii2-jumbefupi extension uses the yii2-httpclient and 'baseUrl' is already set in the yii2-jumbefupi extension itself. The current API base URL is https://api.jumbefupi.com/v2

use danvick\jumbefupi\TextMessage;
...
Yii::$app->jumbefupi->send(new TextMessage(['recipients' => $recipients, 'text' => $message]))

$recipients: A string of comma separated phone numbers or an array of phone number string

$message: Text message to send

$senderId (OPTIONAL): The alphanumeric SenderId shown as message sender to user. Optional if already set in jumbefupi component in config

Fetching messages

List messages

Retrieve a paginated list of messages for the authenticated account, newest first by default.

$result = Yii::$app->jumbefupi->getMessages(
    page: 1,
    perPage: 20,
    filters: [
        'status'       => 'delivered',   // optional — exact match
        'sender_id'    => 'MYAPP',       // optional — exact match
        'phone_number' => '0712',        // optional — partial match
        'created_at'   => '2024-01-01 - 2024-01-31', // optional — date range
    ],
    sort: '-created_at'  // optional — prefix '-' for descending; supported: created_at, status, cost, sms_count
);

The returned array has three keys:

Key	Type	Description
`messages`	`array`	Array of message objects (see fields below)
`pagination`	`array`	`total_count`, `page_count`, `current_page`, `per_page`
`links`	`string`	RFC 5988 `Link` header value with `first`, `prev`, `next`, `last` rel links

Get a single message

Fetch the full details of one message by its ID.

$message = Yii::$app->jumbefupi->getMessage($messageId);

$messageId: The message ID (ULID) found in the message_id field of a previously sent or listed message.

The returned array contains:

Field	Type	Description
`message_id`	`string`	Unique message identifier
`phone_number`	`string`	Recipient phone number
`text`	`string`	Message body
`cost`	`float`	Cost charged for this message
`status`	`string`	Current delivery status (e.g. `delivered`, `queued`)
`status_message`	`string`	Human-readable status description
`sms_count`	`int`	Number of SMS parts
`created_at`	`string`	ISO 8601 timestamp when the message was created
`last_status_update`	`string\|null`	ISO 8601 timestamp of the last status change, or `null`
`request_id`	`string`	ID of the send request that created this message
`text_encoding`	`string\|null`	Encoding used (e.g. `GSM7`, `UNICODE`)

Handling status callbacks / Check message status

You can either create an endpoint to handle message status callback so that when the message status changes (e.g. when message is delivered or otherwise) or manually calling getMessageStatus() function

Setting up a callback

Set up an action to handle callbacks from the gateway then update the message status in DB. It's important that this action be unauthenticated

The server response to the callback will take the following shape:
```
{
    "message_id": "517E70B0F3A611EC84223E99B9487780",
    "phone_number": "0700000000",
    "cost": 1.0,
    "status": "queued",
    "status_message": "Added to queue",
    "sms_count": 1
}
```
Manually calling getMessageStatus() to get message status
```
Yii::$app->jumbefupi->getMessageStatus($messageId)
```
$messageId: message identifier found within the message_id column in the sms_message table

The message will be automatically updated in the DB on successful server response.

Checking your JumbeFupi account balance

Returns your JumbeFupi account balance. The balance can be cached if cacheBalance is set to true in config. The cached balance if any will be deleted on sending message(s)

Yii::$app->jumbefupi->checkBalance($fromCache)

$fromCache: Boolean to enable getting cached balance if available or to ignore cached value. Only useful when cacheBalance is set to true in config

API Documentation

See the API documentation for more information here: JumbeFupi API Docs

danvick / yii2-jumbefupi

Maintainers

Package info

Statistics

Security