README

Overview Karix API lets you interact with the Karix platform using an omnichannel messaging API. It also allows you to query your account, set up webhooks and buy phone numbers. # API Endpoint https://api.karix.io/ # API and Clients Versioning Karix APIs are versioned using the format vX.Y where X is the major version number and Y is minor. All minor version releases are backwards compatible but major releases are not, please be careful when upgrading. Version header `api-version` is used by Karix platform to determine the version of the API request. To use Karix API v2 you can send `api-version` as `\"2.0\"`. If an API request does not contain `api-version` header then Karix platform uses the pinned API version of the account as the default verison. Your account defaults to the latest API version release at the time of signup. You can check the pinned API version form the dashboard. Karix also provides Helper Libraries for all major languages. Release versions of these libraries correspond to their API Version supported. Client version vX.Y.Z supports API version vX.Y. Helper libraries are configured to send `api-version` header based on the library version. When using official Karix helper libraries, you dont need to concern yourself with pinned version. Using helper library of latest version will give you access to latest features. # Supported Channels Karix omnichannel messaging API supports the following channels: - sms - whatsapp ## SMS Channel To send a message to one or more destinations over SMS channel set `channel` to `sms` in the Messaging API. In trial mode, your account can only send messages to numbers within the sandbox. ## Whatsapp Channel To send a message to a destination over WhatsApp channel set `channel` to `whatsapp` in the Messaging API. By default WhatsApp channel can only be used from within the sandbox. Contact support for sending message outside the sandbox and getting your own Whatsapp Business Account. ### Message Types Any messages you initiate over WhatsApp to end users must conform to a template configured in WhatsApp. These messages are called "Notification Messages". Both text and media content can be sent as a notification message. Please contact your sales representative to get templates approved (or mail sales) Any responses you receive from end users and all replies you send within 24 hours of the last received response are called "Conversation Messages". Both Notification and Conversation messages are priced differently, please refer to the pricing page for more details. #### Text Notification To send a notification message with text content the `content.text` parameter in Send Message API request needs to match an approved template pattern. When using the sandbox for testing and development purposes, we have provided for the following pre-approved templates for "Notification Messages": - Your order * has been dispatched. Please expect delivery by * - OTP requested by you on * is * - Thank you for your payment of * * on . Your transaction ID is You can replace `` with any text of your choice. #### Media Notification To send a notification message with media content the `content.media.caption` parameter in Send Message API request needs to match an approved template pattern. Additionally, the `content.media.url` parameter should link to a media type which is approved for that pattern. The following media types can be supported: image, video (only MP4), and document (only PDF). When using the sandbox for testing and development purposes, we have provided for the following pre-approved templates for "Notification Messages": - Caption: Your Ticket for movie On * Time * Seat no : * Media Type: image - Caption: Hey here is the demo on steps to install * Media Type: video - Caption: Flight Confirmation for * on * Media Type: document You can replace `*` with any text of your choice. ### Content Types WhatsApp supports the following content types for outbound media messages: | Content Type | File Format | |:------------ |:------------------------------------ | | audio | AAC, M4A, AMR, MP3, OGG OPUS | | image | JPG/JPEG, PNG | | documents | PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX | | video | MP4, 3GPP | Besides video content, it is also possible to send links to sites which support preview (like YouTube) as a conversation text message. WhatsApp will render video preview depending on the user's device. For inbound media, Karix supports all file formats which can be sent using WhatsApp. An incoming media message event will be reported to the Webhook attached to the Number resource. You can read more about Karix event structure here. # Common Request Structures All Karix APIs follow a common REST format with the following resources: - account - message - webhook - number ## Creating a resource To create a resource send a `POST` request with the desired parameters in a JSON object to `/<resource>/` url. A successful response will contain the details of the single resource created with HTTP status code `201 Created`. Note: An exception to this is the `Create Message` API which is a bulk API and returns a list of message records. ## Fetching a resource To fetch a resource by its Unique ID send a `GET` request to `/<resource>/<uid>/` where `uid` is the Alphanumeric Unique ID of the resource. A successful response will contain the details of the single resource fetched with HTTP status code `200 OK` ## Editing a resource To edit certain parameters of a resource send a `PATCH` request to `/<resource>/<uid>/` where `uid` is the Alphanumeric Unique ID of the resource, with a JSON object containing only the parameters which need to be updated. Edit resource APIs generally have no required parameters. A successful response will contain all the details of the single resource after editing. ## Deleting a resource To delete a resource send a `DELETE` request to `/<resource>/<uid>/` where `uid` is the Alphanumeric Unique ID of the resource. A successful response will return HTTP status code `204 No Content` with no body. ## Fetching a list of resources To fetch a list of resources send a `GET` request to `/<resource>/` with filters as GET parameters. A successful response will contain a list of filtered paginated objects with HTTP status code `200 OK`. ### Pagination Pagination for list APIs are controlled using GET parameters: - `limit`: Number of objects to be returned - `offset`: Number of objects to skip before collecting the output list. # Common Response Structures All Karix APIs follow a common respose structure. ## Success Responses ### Single Resource Response Responses returning a single object will have the following keys | Key | Child Key | Description | |:------------- |:------------- |:----------------------------------------- | | meta | | Meta Details about request and response | | | request_uuid | Unique request identifier | | data | | Details of the object | ### List Resource Response Responses returning a list of objects will have the following keys | Key | Child Key | Description | |:------------- |:------------- |:----------------------------------------- | | meta | | Meta Details about request and response | | | request_uuid | Unique request identifier | | | previous | Link to the previous page of the list | | | next | Link to the next page of the list | | | total | Total number of objects over all pages | | objects | | List of objects with details | ## Error Responses ### Validation Error Response Responses for requests which failed due to validation errors will have the follwing keys: | Key | Child Key | Description | |:------------- |:------------- |:------------------------------------------ | | meta | | Meta Details about request and response | | | request_uuid | Unique request identifier | | error | | Details for the error | | | message | Error message | | | param | (Optional) parameter this error relates to | Validation error responses will return HTTP Status Code `400 Bad Request` ### Insufficient Balance Response Some requests will require to consume account credits. In case of insufficient balance the following keys will be returned: | Key | Child Key | Description | |:------------- |:------------- |:----------------------------------------- | | meta | | Meta Details about request and response | | | request_uuid | Unique request identifier | | error | | Details for the error | | | message | `Insufficient Balance` | Insufficient balance response will return HTTP Status Code `402 Payment Required` # Events and Webhooks All asynchronous events generated by Karix platform follow a common structure: | Key | Child Key | Description | |:------------- |:------------- |:------------------------------------------- | | uid | | Alphanumeric unique ID of the event | | api_version | | 2.0 | | type | | Type of the event. | | data | | Details of the object attached to the event | On an asynchronous event, an HTTP POST request is sent with the above JSON playload. - For outbound messages, a message event is sent to events_url specified in Send Message API. - For inbound messages, a message event is either sent to the `events_url` of the Webhook attached to the Number or the Sandbox URL configured in the Dashboard. ## Events List ### Outbound Message Status Update `message` events are generated when a message status is changed to `sent`, `delivered`, `undelivered` or `failed`. These events are sent to `events_url` parameter of Send Message API ### Inbound Message Received `message` events are generated when a message is received on a Number with capability to receive messages on a channel. These events are sent to the webhook attached to the phone number resource using Edit Number API For inbound messages to WhatsApp Sandbox, `message` events are sent to Webhook URL set on the Dashboard. ### Inbound Media Message Received `message` events are generated when a message containing media content is received on a Number with capability to receive messages through a media capable channel. An inbound message to WhatsApp Sandbox may also contain media. The parameter `data.content.media.url` will link to the Media URL hosted with Karix from where you can download the media.

This PHP package is automatically generated by the Swagger Codegen project:

API version: 2.0
Build package: io.swagger.codegen.languages.PhpClientCodegen

Requirements

PHP 5.5 and later

Installation & Usage

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "git",
      "url": "https://github.com//.git"
    }
  ],
  "require": {
    "/": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

    require_once('/path/to/SwaggerClient-php/vendor/autoload.php');

Tests

To run the unit tests:

composer install
./vendor/bin/phpunit

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configure HTTP basic authorization: basicAuth
$config = Swagger\Client\Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_USERNAME')
    ->setPassword('YOUR_PASSWORD');

$apiInstance = new Swagger\Client\Api\AccountsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$api_version = "2.0"; // string | API Version. If not specified your pinned verison is used.
$subaccount = new \Swagger\Client\Model\CreateAccount(); // \Swagger\Client\Model\CreateAccount | Subaccount object

try {
    $result = $apiInstance->createSubaccount($api_version, $subaccount);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AccountsApi->createSubaccount: ', $e->getMessage(), PHP_EOL;
}

?>

Documentation for API Endpoints

All URIs are relative to https://api.karix.io

Documentation For Models

Documentation For Authorization

basicAuth

Type: HTTP basic authentication

Author

support@karix.io

samuelbie / karix-php

Maintainers

Details