Zigatext API - v1.0.0

Zigatext messaging platform is everything you need for your mobile marketing, OTP, etc.

• SMS Broadcasting - Bulk/Single SMS
• Advanced Scheduling - with recurrence and random delivery time
• Location based SMS Campaign
• Transactional SMS - OTP, receipt and account balance
• SMS Newsletter - with Opt-in autoresponder followup
• Auto Birthday SMSing like banks
• Personalize SMS by Tagging

Introduction

Zigatext API is RESTful. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

https://api.zigatext.com/v1

Getting started

• Login to your Zigatext dashboard on the portal https://app.zigatext.com
• Go-to General Settings (at the topright menu) > Profile tab and change your account type to Corporate - to enable you Integrate Zigatext into third-party projects.
• Click Projects tab and create project, the Access Key generated for the project is what you’ll be using to access our services.
• Go-to Ziga Units (at the topright menu) > Fund Project tab and transfer units from your main Zigatext account to the project.

If the project units finishes your main units will not be touched unless you transfer more units to project.

You can use one Zigatext account to manage many projects.

Important! Sender name registration is now mandatory. Kindly submit your sender name for registration by logging into your Zigatext account:

• Click Message Box menu item then + Register Sender Name button.

Authentication

The Zigatext API uses Access key to authenticate requests. You can view and manage your projects API keys in the Zigatext Dashboard.

For Raw HTTP request include Access-Key to the http request header with your access key as the value.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

API calls

All your requests must carry Access-Key http header with your project access key as the value and all POST requests must be JSON-encoded Content-Type: application/json

Sending messages

POST [/third-party/messages/send]

{
  "sender":"dev-group",
  "message": "Your awesome message",
  "recipients": "23470xxxxxxxx",
  "use_corporate_route": false,
  "callback_url": ""
}

Send request parameters

• sender is your custom name/title for your message and it should not exceed 11 characters (space is also counted as character)
• recipients the phone number(s) you want to receive your message. Phone number is in intl format (meaning that phone number should include zipcode)
• message is the content you want to send to your recipient(s)
• use_corporate_route can either be true or false. Value ‘true’ means that you want your message delivers to Do-Not-disturb (DND) numbers for countries that has dnd policy
• callback_url when you submit message for sending our server queue’s the message for delivery and after delivery your callback url is called to notify your system/website that your message has been sent. Then you can use the message id passed as query string to retrieve delivery details. This parameter is optional in case you don’t want to receive callback

Scheduling message

POST [/third-party/messages/schedule]

{
	"sender":"zigatext",
	"recipients":"23470xxxxxxxx,23480xxxxxxxx",
	"use_corporate_route":true,
	"extras":[
		{
			"deliver_at":"2018-06-17 17:50:00",
			"time_zone_id":1018
		}
	],
	"message":"it is awesome",
    "callback_url": ""
}

Schedule request parameters

Most of the parameter are the same with send method above.

• extras accepts arrays of delivery times, in case you want your scheduled message to deliver at different times.
• time_zone_id You can call our time zone endpoint to get list of timezones and their ids. It’s used to set at what timezone you want your scheduled message to delivery to your recipient(s)

Fetch sent message

GET [/third-party/messages/{sentID}]

Fetch sent message extra

GET [/third-party/messages/{sentID}/extras]

Fetch newsletter lists

GET [/third-party/newsletters]

Single subscriber opt-in

POST [/third-party/newsletters/{newsletterID}/subscribers]

{
  "name": "Subscriber's name",
  "phone_no": "23470xxxxxxxx"
}

Newsletter opt-in request parameters

To add subscriber from your system/website to your Newsletter list, first login to your Zigatext dashboard, create the newsletter list and associate it to your project. Next call Newsletter endpoint to pull your list with their ids

• name subscriber’s name.
• phone_no subscriber’s phone number

Bulk subscribers opt-in

POST [/third-party/newsletters/{newsletterID}/subscribers/bulk]

{
  "subscribers": [
    {
      "name": "Subscriber 1",
      "phone_no": "23470xxxxxxxx"
    },
    {
      "name": "Subscriber 2",
      "phone_no": "23480xxxxxxxx"
    }
  ]
}

Newsletter opt-in request parameters

This is same as adding single subscriber but in this case you add multiple subscribers at once

Fetch birthday groups

GET [/third-party/birthdays/groups]

Add single birthday contact

POST [/third-party/birthdays/{groupID}/contacts]

{
  "name": "Chibuike Mba",
  "phone_no": "234703xxxxxxx",
  "day": 9,
  "month_id": 1
}

Add birthday contact request parameters

To add contact from your system/website to your birthday group, first login to your Zigatext dashboard and create the birthday group. Next call Birthday endpoint to pull your groups with their ids

• name celebrant’s name
• phone_no celebrant’s phone number
• day day of the month
• month_id month id is from 1 - 12

Add bulk birthday contacts

POST [/third-party/birthdays/{groupID}/contacts/bulk]

{
  "contacts": [
    {
      "day": 19,
      "month_id": 7,
      "name": "Benjamin Akawu",
      "phone_no": "23481xxxxxxx"
    },
    {
      "day": 30,
      "month_id": 5,
      "name": "Bernard Inyang",
      "phone_no": "234806xxxxxxx"
    },
    {
      "day": 05,
      "month_id": 3,
      "name": "Khaleb Uche",
      "phone_no": "234810xxxxxxx"
    }
  ]

Birthday contacts request parameters

This is same as adding single contact but in this case you add multiple contacts at once

Fetch time zones

GET [/third-party/time-zones]

Check balance

GET [/third-party/check-balance]

Fetch months

GET [/third-party/months]

API calls

All your requests must carry Access-Key http header with your project access key as the value and all POST requests must be JSON-encoded Content-Type: application/json

Sending verification OTP or TOTP

POST [/third-party/verifications/verify-number]

{
  "type":"OTP",
  "validity": 0,
  "phone_no": "23470xxxxxxxx",
  "sender": "Zigatext"
}

Send OTP/TOTP parameters

• type is verification method: One-Time Password (OTP), Timed One-Time Password (TOTP), IVR (not functional), CLI (missed call, not functional)
• validity the life span of the PIN, non zero value for TOTP
• phone_no recipient phone number
• sender this is used to identify the app the verification pin is meant for

Verification PIN Validation

POST [/third-party/verifications/verify-pin]

{
	"id": 1,
	"pin": "909075",
	"phone_no": "23470xxxxxxxx"
}

Verification PIN Validation request parameters

Most of the parameter are the same with send method above.

• id once the verification pin is successfully sent, the response payload of Send OTP/TOTP comes with ID property, its expected to be stored and used here during pin validation.
• pin the pin the user received.
• phone_no recipient’s phone number.