Send SMS from your own software

A REST API with JSON in and out, and SMPP for systems that already use it. Everything is under https://api.hovagh.com/v1.

Keys

Create keys in your dashboard under Developer tools. Send the key as a bearer token. Keys starting sk_test_ go through every check but send nothing and charge nothing, so you can build and test for free. Keys starting sk_live_ send real messages. Hova stores only a hash of each key, so copy it when it's shown.

Send a text

curl https://api.hovagh.com/v1/messages/sms \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0241234567",
    "body": "Your order #1042 is ready for pickup.",
    "from": "YOUR-SHOP",
    "clientReference": "order-1042"
  }'

to: A Ghanaian mobile number. 024…, 233… and +233… are all accepted.
body: The message. Up to 160 plain characters is one SMS; longer messages are sent and charged in parts.
from: Optional. One of your approved sender names. Without it Hova uses your default sender, then HOVA-INFO.
clientReference: Optional but recommended. Your own ID for the message. If you send the same reference again, Hova returns the first message instead of texting the person twice, so retries are safe.
scheduledAt: Optional. An ISO date and time to send later.

Send to many

Up to 500 people per request. Give a default body, or a body for each person.

POST /v1/messages/sms/bulk
{
  "from": "YOUR-SCHOOL",
  "body": "School resumes on Monday 5 May.",
  "clientReference": "resumption-may",
  "recipients": [
    { "to": "0241234567" },
    { "to": "0201234567", "body": "Dear Mrs Mensah, school resumes on Monday 5 May." }
  ]
}

Delivery reports

Add your server's address under Developer tools, Webhooks. Hova posts sms.delivered and sms.failed as the networks report them. Each request carries an X-CPaaS-Signature header, t=<timestamp>,v1=<hex>, where the hex is an HMAC-SHA256 of <timestamp>.<body> with your endpoint's signing secret. Check it before trusting the request. You can also look up a message with GET /v1/messages/sms/<id>.

SMPP

Create an SMPP login under Developer tools. Connect to smpp.hovagh.com on port 2775, or 3550 for TLS, with SMPP 3.4. Delivery receipts come back as deliver_sm. Each login can be limited to the IP addresses you list.

Software built for another gateway

Code written for mNotify, Arkesel, Hubtel or SMSOnlineGH works unchanged. In the dashboard, open Connect software and choose the gateway; Hova gives you an address under https://api.hovagh.com/compat/ and a key to paste in. How switching works.

Full reference

Every endpoint, field and error is in the OpenAPI description: openapi.json. Load it into Postman, Insomnia or a code generator.

Libraries

Node.jsBeing published. Email support@hovagh.com for an early copy.
PythonBeing published. Email support@hovagh.com for an early copy.
JavaBeing published. Email support@hovagh.com for an early copy.
PHPBeing published. Email support@hovagh.com for an early copy.