Public SMS API

Your access token:

{accessToken}

This access token belongs to your user {userId}.

In order to authenticate your request you need to pass it in request's header Authorization. The value must be prefixed with the Bearer string:

Authorization: Bearer {yourToken}

To send an SMS you need a number. The easiest way is to buy it via the OnPhone Web UI and then grab its ID from the API call:

curl -H 'Authorization: Bearer {yourToken}' https://onphone.app/api/v1/users/numbers

You need to take the id field from the response.

In order to send an SMS, perform the next request. Take a note that there is a {numberId} param in URL, which must be replaced to the corresponding phone number. The request body might be sent as a application/x-www-form-urlencoded, application/json or multipart/form-data serialized string. In the example below JSON body is used.

curl -X POST \
     -H 'Authorization: Bearer {yourToken}' \
     -H 'Content-Type: application/json' \
     -d '{"message": "Hello world", "to": "+918878629004"}' \
     https://onphone.app/api/v1/numbers/{numberId}/sms

In case of successful submit you will receive a response with 200 status and JSON content of sent message. In case of an error you will receive a response with 400 status code and JSON content with key-value pairs (field-error) describing the error. The most expected errors are:

Not enough balance credits:

{"user": "error.not_enough_credits"}

Unable to text on an unidentified problem from an external provider:

{"to": "error.cannot_send_sms"}

Message object schema:

{
  "id": "string",
  "from": "string",
  "to": "string",
  "isIncoming": "boolean",
  "isDetained": "boolean",
  "isAutoreply": "boolean",
  "isForwarded": "boolean",
  "usedNumberId": "string",
  "message": "string",
  "files": ["string"],
  "status": "string",
  "credits": "integer",
  "shouldSendAt": "integer",
  "createdAt": "integer"
}

The message status can have the following values: sent, queued, delivered, undelivered, failed, received.

To get the final status of a sent message, you can use the following query. Take a note that there is a {id} param in URL, which must be replaced to the corresponding message id:

curl -H 'Authorization: Bearer {yourToken}' https://onphone.app/api/v1/messages/{id}

Request to get a list of dialogues for a specific number. Take a note that there is a {numberId} param in URL, which must be replaced to the corresponding phone number:

curl -H 'Authorization: Bearer {yourToken}' https://onphone.app/api/v1/users/numbers/{numberId}/dialogues

The response will contain an array of dialogues for the specified number. Dialogues are sorted by the date of the last message, from newest to oldest. The response can contain a maximum of 300 dialogues. If the specified number has more than 300 dialogues, then you need to repeat the request specifying the before parameter in query. The value of the before parameter must be the value of the lastMessageCreatedAt parameter from the oldest dialog from the previous list of dialogues:

curl -H 'Authorization: Bearer {yourToken}' https://onphone.app/api/v1/users/numbers/{numberId}/dialogues?before=1772375695

Dialogue object schema:

{
  "isPinned": "boolean",
  "hasScheduledMessages": "boolean",
  "numberId": "string",
  "toNumber": "string",
  "lastMessageCreatedAt": "integer",
  "latestMessage": "MessageObject"
}

Request for a specific dialogue. Take a note that there is a {numberId} and {withNumber} params in URL, which must be replaced to the corresponding phone number and by one of the numbers from the toNumber parameter from the previous request:

curl -H 'Authorization: Bearer {yourToken}' https://onphone.app/api/v1/users/numbers/{numberId}/messages/{withNumber}

The response will contain an array of messages for the specified dialogue.

{
  "data": ["MessageObject"]
}

Messages are sorted by the date of message, from newest to oldest. The response can contain a maximum of 100 messages. If the specified dialogue has more than 100 messages, then you need to repeat the request specifying the before parameter in query. The value of the before parameter must be the value of the createdAt parameter from the oldest message from the previous list of messages:

curl -H 'Authorization: Bearer {yourToken}' https://onphone.app/api/v1/users/numbers/{numberId}/messages/{withNumber}?before=1772375695