NAV Navbar
shell

Introduction

Welcome to the documentation for Moya Messaging API. Please note that we are currently in beta. If you run into any issues, or have questions / feedback on how we can improve, please let us know by sending a message to api-support@moya.app.

Authentication

To access the Messaging API, you will need an access token. In order to obtain one, please send a message to api-support@moya.app specifying the mobile number that you would like to use.

The Moya Business API uses Bearer tokens for authentication (please see RFC-6750 standard for more information). You can pass the token in one of two ways:

Messages

Send Message

To send a message, simply send a POST request to as shown in the example. Please ensure recipient_type is set to "individual" and that type is set to "text".

HTTP Request

POST https://api.moya.app/v1/message

Example Request

curl --location --request POST 'https://api.moya.app/v1/message' \
  --header 'Authorization: Bearer YourSecretToken' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "to":"27…1",
    "recipient_type":"individual",
    "type":"text",
    "text":
    {
      "body":"Hello World"
    }
  }'

Example Response

{"id":"188cec25-dff0-480b-8e19-68023424e835"}

Parameters

Name Type Required Description
to String Yes This field is for the phone number of the user that you wish to message.
recipient_type String Yes Must be set to "individual".
type String Yes Must be set to "text".
text JSON Object Yes Contains the body field
text.body String Yes The message body goes here.

Receive Message

Incoming messages will be sent via HTTP POST in the format below:

{
  "message":
    {
      "type":"text",
      "from":"27123456789",
      "text":
        {
          "body":"Hello"
        }
     }
}

To receive messages via your Moya API integration, you need to provide us with a URL "inbox" where the messages can be sent to (e.g. https://your.webservice.com/secret/moya-event-endpoint).

Contacts

Checking Contacts

To check if a list of user phone numbers from your database correspond to valid Moya accounts, please submit a POST request as shown in the examples provided in the right side.

The /v1/contacts endpoint supports 2 formats in which a list of numbers can be submitted, plaintext and hashed (for added security in transmitting a list of your contacts over the Internet). Please use the hashed parameter (bool), to indicate whether you are submitting a list of .

Example Request 1 with plaintext numbers

curl --location --request POST 'https://api.moya.app/v1/contacts' \
--header 'Authorization: Bearer YourSecretToken' \
--header 'Content-Type: application/json' \
--data-raw '{
  "contacts": [
    "27123456789",
    "27000000000",
    "27987654321"
  ]
}'

Example Response (1 of the submitted numbers identified as a Moya user and returned)

{
    "error": false,
    "match_count": 1,
    "match_list": ["27123456789"]
}

Example Request with hashed numbers

curl --location --request POST 'https://api.moya.app/v1/contacts' \
--header 'Authorization: Bearer YourSecretToken' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contacts": [
    "FD9F304A987B7354A6AF8BF25ECD63DD32F8D7349F6473B890F0320613D04470",
    "555CDE815EF46CC7F2C1B0EAFD78F04E1293061FCC176E6A8202AE1C3A47080F",
    ],
    "hashed":true
}'

Example Response (1 of the submitted numbers identified as a Moya user and returned)

{
    "error": false,
    "match_count": 1,
    "match_list": ["FD9F304A987B7354A6AF8BF25ECD63DD32F8D7349F6473B890F0320613D04470"]
}

HTTP Request

POST https://api.moya.app/v1/contacts

Parameters

Name Type Required Description
contacts Array Yes Array of phone numbers (up to 1000 at a time) that you are validating. The numbers must be in international format, excluding trailing zeros and plus sign (e.g.: 27123456789). When using hashed parameter, the numbers should be hashed first. If you provide plaintext numbers with this parameter on, lookup will fail.
hashed Boolean Yes Set this to true if the numbers are being transmitted in hashed format. Defaults to false.

Here is a diagram representing an example process flow to check for user base overlap, in more detail. Number checking diagram