Introduction
JookSMS is an SMS system that allows you to connect with your clients either chatting with them using SMS messages or by sending them mass SMS for a promotion or any information you need.
It also allows you to set up triggers and automatically react when: - A server or website fails - You receive an email - You receive an SMS - Or integrate with any other system through webhooks
But, also we provide an API so you can integrate JookSMS with your system in any way you need to.
If you have not created your account then proceed to claim your Free Trial right now Sign in / Register
Authentication
Process
- First use your ID and Secret from this page to request a valid session token.
- Use this token in the header of every request to the API.
The token will be valid for 1 hour.
To authorize, use this code:
curl -X POST --data 'client_id=[YOUR ID]&client_secret=[YOUR SECRET]' \
https://sms.jooksms.com/api/v1/oauth/access_token
// TBD
Returns
{
"access_token":"[YOUR NEW TOKEN]",
"token_type":"Bearer",
"expires_in":3600
}
Request token
| Parameter | Description |
|---|---|
| client_id | The API client ID |
| client_secret | The API client secret |
SMS Messages
Get SMS Information Using SMS ID
curl -H "Authorization: Bearer [YOUR NEW TOKEN]" \
https://sms.jooksms.com/api/v1/sms/[SMS ID]
\\ TBD
Returns:
{
"data": {
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "To nestor test",
"created": {
"date": "2016-06-26 19:59:36.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 113,
"number": "+50768819519",
"status": "sent"
},
"result": "ok"
}
Parameters:
| Parameter | Description |
|---|---|
| SMS ID | The ID of the SMS, got when sent by other call. |
Get SMS Information Using External ID
curl -H "Authorization: Bearer [YOUR NEW TOKEN]" \
https://sms.jooksms.com/api/v1/sms/by_external/[External ID]
// TBD
Returns:
{
"data": {
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing API 001",
"created": {
"date": "2016-06-26 17:27:11.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": 900,
"id": 106,
"number": "+50768819519",
"status": "sent"
},
"result": "ok"
}
Parameters:
| Parameter | Description |
|---|---|
| External ID | The external ID attached to the SMS when sent by another call. |
Send a message (using JSON for the request)
Parameters:
curl -X POST -d '{
"to": "+50768819519",
"from": "50672004393",
"scheduled": "2016/06/26 10:00 GMT-5",
"body": "Just a test",
"external_id":999}' \
-H "Authorization: Bearer [YOUR NEW TOKEN]" \
-H "Content-Type: application/json" \
https://sms.jooksms.com/api/v1/sms/
\\ TBD
Returns:
{
"data": {
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Just a test",
"created": {
"date": "2016-06-26 17:27:11.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": 999,
"id": 106,
"number": "+50768819519",
"status": "queued"
},
"result": "ok"
}
| Parameter | Required | Description |
|---|---|---|
| to | Yes | The phone number you want to send the SMS to |
| body | Yes | The message |
| from | No | The phone number you own and want to send the SMS from. If not given or invalid we would use the first phone number we find in your account. |
| scheduled | No | A date/time you want this message to be sent. Format: yyyy/mm/dd hh:mm TZ |
| external_id | No | An integer that can serve as a reference to your own system, you can after request using this ID |
Send a message (using normal post request -no json-)
curl -X POST \
-d "to=%2B50768819519&from=50672004393&external_id=999&scheduled=2016/06/26 10:00 GMT-5&body=Just a test" \
-H "Authorization: Bearer [YOUR NEW TOKEN]" \
https://sms.jooksms.com/api/v1/sms/
\\ TBD
Send one message to many recipients
curl -X POST -d '{
"from": "50672004393",
"body": "Just a test",
"list": [
{
"to":"+50768819519",
"first_name":"Test",
"last_name":"Doe"
"external_id":901
},
{
"to":"+50767832484",
"external_id":902
}
]}' \
-H "Authorization: Bearer [YOUR NEW TOKEN]" \
-H 'Content-Type: application/json' \
https://sms.jooksms.com/api/v1/sms/to_many
\\ TBD
Returns: (list of ID's or -1 if a message had an error)
{
"result":"ok",
"ids":[110,111]
}
Parameters:
| Parameter | Required | Description |
|---|---|---|
| body | Yes | The message to send to all recipients |
| from | No | The phone number you own and want to send the SMS from. If not given or invalid we would use the first phone number we find in your account. |
| scheduled | No | A date/time you want this message to be sent. Format: yyyy/mm/dd hh:mm TZ |
| list | Yes | The list containing the recipient information. |
List Parameter
The list parameter is an array of 2 parameters each:
| Parameter | Required | Description |
|---|---|---|
| to | Yes | The phone number you want to send the SMS to |
| external_id | No | An integer that can serve as a reference to your own system, you can after request using this ID |
| first_name | No | Contact First Name, in case you want to create/update a contact for this number (if contact exists then it updates the information) |
| last_name | No | Contact Last Name |
| scheduled | No | In case you want to specified a time to send this specific message |
Send different messages to many recipients
curl -X POST -d '{
"from": "50672004393",
"list": [
{
"to":"+50768819519",
"body":"To test user",
"first_name":"Test",
"last_name":"Doe"
},
{
"to":"+50767832484",
"body":"to Joe test",
"scheduled": "2018-03-22 10:20 +0600"
}
]}' \
-H "Authorization: Bearer [YOUR NEW TOKEN]" \
-H 'Content-Type: application/json' \
https://sms.jooksms.com/api/v1/sms/many
\\ TBD
Returns: (list of ID's or -1 if a message had an error)
{
"result":"ok",
"ids":[112,113]
}
Parameters:
| Parameter | Required | Description |
|---|---|---|
| from | No | The phone number you own and want to send the SMS from. If not given or invalid we would use the first phone number we find in your account. |
| scheduled | No | A date/time you want this message to be sent. Format: yyyy/mm/dd hh:mm TZ |
| list | Yes | The list containing the recipient information. |
List Parameter
The list parameter is an array of 3 parameters each:
| Parameter | Required | Description |
|---|---|---|
| to | Yes | The phone number you want to send the SMS to |
| body | Yes | The message to send to this recipient |
| external_id | No | An integer that can serve as a reference to your own system, you can after request using this ID |
| first_name | No | Contact First Name, in case you want to create/update a contact for this number (if contact exists then it updates the information) |
| last_name | No | Contact Last Name |
| scheduled | No | In case you want to specified a time to send this specific message |
List of messages (paginated)
curl --header "Authorization: Bearer [YOUR NEW TOKEN]" \
https://sms.jooksms.com/api/v1/sms/
// TBD
Returns:
{
"result": "ok",
"meta": {
"pagination": {
"count": 15,
"current_page": 1,
"links": {
"next": "https://sms.jooksms.com/api/v1/sms?page=2"
},
"per_page": 15,
"total": 111,
"total_pages": 8
}
},
"data": [
{
"contact": {
"data": {
"display_name": "Laura Araya",
"first_name": "Laura",
"id": 4,
"is_public": 0,
"last_name": "Araya",
"main_phone": "+50767832484",
"status": 0
}
},
"content": "to laura test",
"created": {
"date": "2016-06-26 19:59:36.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 114,
"number": "+50767832484",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "To nestor test",
"created": {
"date": "2016-06-26 19:59:36.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 113,
"number": "+50768819519",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Laura Araya",
"first_name": "Laura",
"id": 4,
"is_public": 0,
"last_name": "Araya",
"main_phone": "+50767832484",
"status": 0
}
},
"content": "Testing more mass structured API",
"created": {
"date": "2016-06-26 19:55:22.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 112,
"number": "+50767832484",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing more mass structured API",
"created": {
"date": "2016-06-26 19:55:22.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 111,
"number": "+50768819519",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Laura Araya",
"first_name": "Laura",
"id": 4,
"is_public": 0,
"last_name": "Araya",
"main_phone": "+50767832484",
"status": 0
}
},
"content": "Testing more mass API",
"created": {
"date": "2016-06-26 19:43:12.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 110,
"number": "+50767832484",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing more mass API",
"created": {
"date": "2016-06-26 19:43:12.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 109,
"number": "+50768819519",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Laura Araya",
"first_name": "Laura",
"id": 4,
"is_public": 0,
"last_name": "Araya",
"main_phone": "+50767832484",
"status": 0
}
},
"content": "Testing mass API",
"created": {
"date": "2016-06-26 19:29:21.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 108,
"number": "+50767832484",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing mass API",
"created": {
"date": "2016-06-26 19:29:21.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 107,
"number": "+50768819519",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing API 001",
"created": {
"date": "2016-06-26 17:27:11.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": 900,
"id": 106,
"number": "+50768819519",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing API 001",
"created": {
"date": "2016-06-26 17:25:19.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 105,
"number": "+50768819519",
"status": "sent"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing API",
"created": {
"date": "2016-06-26 17:13:33.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 104,
"number": "+50768819519",
"status": "sent"
},
{
"content": "Mi clave 8496 y la de mi mama 2253",
"created": {
"date": "2016-06-26 17:08:45.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "incoming",
"external_id": null,
"id": 103,
"number": "+50650191906",
"status": "received"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing API",
"created": {
"date": "2016-06-26 17:01:22.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 102,
"number": "+50768819519",
"status": "queued"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing API",
"created": {
"date": "2016-06-26 16:58:22.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 101,
"number": "+50768819519",
"status": "queued"
},
{
"contact": {
"data": {
"display_name": "Nestor Panama",
"first_name": "Nestor",
"id": 1,
"is_public": 0,
"last_name": "Panama",
"main_phone": "+50768819519",
"status": 0
}
},
"content": "Testing API",
"created": {
"date": "2016-06-26 16:56:46.000000",
"timezone": "UTC",
"timezone_type": 3
},
"direction": "sending",
"external_id": null,
"id": 100,
"number": "+50768819519",
"status": "queued"
}
]
}
Contacts
Get Contact Information
curl -H "Authorization: Bearer [YOUR NEW TOKEN]" \
https://sms.jooksms.com/api/v1/contact/[Contact ID]
\\ TBD
Returns:
{
"data": {
"display_name": "John Doe",
"first_name": "John",
"id": 12278,
"is_public": 0,
"last_name": "Doe",
"main_phone": "+5321235135",
"reference": null,
"status": 0
},
"result": "ok"
}
Parameters:
| Parameter | Required | Description |
|---|---|---|
| Contact ID | Yes | The ID of the contact, obtained when sent by other call. |
Create a contact (using JSON for the request)
curl -X POST -d '
{
"first_name": "John",
"last_name": "Doe",
"main_phone": "+13014438888",
"reference": "ABC"
}' \
-H "Authorization: Bearer [YOUR NEW TOKEN]" \
-H "Content-Type: application/json" \
https://sms.jooksms.com/api/v1/contact/
\\ TBD
Returns:
{
"data": {
"display_name": "John Doe",
"first_name": "John",
"id": 12292,
"is_public": null,
"last_name": "Doe",
"main_phone": "+13014438888",
"reference": "ABC",
"status": null
},
"result": "ok"
}
Parameters:
| Parameter | Required | Description |
|---|---|---|
| first_name | Yes | The contact's first name |
| last_name | Yes | The contact's last name |
| main_phone | Yes | The phone where the contact will receive the messages |
| reference | An optional reference that you can use to identify the contact in some way related with your system | |
| contact_group_id | The ID of the contact group where you want the contact to be added |
Send a message (using normal post request -no json-)
curl -X POST \
-d "first_name=John&last_name=Doe&main_phone=%2B1301585886967&reference=ABC" \
-H "Authorization: Bearer [YOUR NEW TOKEN]" \
https://sms.jooksms.com/api/v1/contact/
\\ TBD
List of contacts (paginated)
curl --header "Authorization: Bearer [YOUR NEW TOKEN]" \
https://sms.jooksms.com/api/v1/contact/
\\ TBD
Returns:
{
"result": "ok",
"meta": {
"pagination": {
"count": 15,
"current_page": 1,
"links": {
"next": "https://sms.jooksms.com/api/v1/contact?page=2"
},
"per_page": 15,
"total": 19,
"total_pages": 2
}
},
"data": [
{
"display_name": "TestI User009",
"first_name": "TestI",
"id": 12278,
"is_public": 0,
"last_name": "User009",
"main_phone": "+5321235135",
"reference": null,
"status": 0
},
{
"display_name": "TestJ User010",
"first_name": "TestJ",
"id": 12279,
"is_public": 0,
"last_name": "User010",
"main_phone": "+53135511351",
"reference": null,
"status": 0
},
{
"display_name": "TestK User011",
"first_name": "TestK",
"id": 12280,
"is_public": 0,
"last_name": "User011",
"main_phone": "+513513513",
"reference": null,
"status": 0
},
{
"display_name": "TestL User012",
"first_name": "TestL",
"id": 12281,
"is_public": 0,
"last_name": "User012",
"main_phone": "+438843553",
"reference": null,
"status": 0
},
{
"display_name": "Laura's Contact",
"first_name": "Laura's",
"id": 12272,
"is_public": 0,
"last_name": "Contact",
"main_phone": "+2135135132",
"reference": null,
"status": 0
},
{
"display_name": "TestA User001",
"first_name": "TestA",
"id": 12273,
"is_public": 0,
"last_name": "User001",
"main_phone": "+5321235135",
"reference": null,
"status": 0
},
{
"display_name": "TestB User002",
"first_name": "TestB",
"id": 12274,
"is_public": 0,
"last_name": "User002",
"main_phone": "+53135511351",
"reference": null,
"status": 0
},
{
"display_name": "TestC User003",
"first_name": "TestC",
"id": 12275,
"is_public": 0,
"last_name": "User003",
"main_phone": "+513513513",
"reference": null,
"status": 0
},
{
"display_name": "TestD User004",
"first_name": "TestD",
"id": 12276,
"is_public": 0,
"last_name": "User004",
"main_phone": "+438843553",
"reference": null,
"status": 0
},
{
"display_name": "TestE User005",
"first_name": "TestE",
"id": 12282,
"is_public": 0,
"last_name": "User005",
"main_phone": "+5321235135",
"reference": "ab0039",
"status": 0
},
{
"display_name": "TestF User006",
"first_name": "TestF",
"id": 12283,
"is_public": 0,
"last_name": "User006",
"main_phone": "+53135511351",
"reference": "ab0040",
"status": 0
},
{
"display_name": "TestG User007",
"first_name": "TestG",
"id": 12284,
"is_public": 0,
"last_name": "User007",
"main_phone": "+513513513",
"reference": "ab0041",
"status": 0
},
{
"display_name": "TestH User008",
"first_name": "TestH",
"id": 12285,
"is_public": 0,
"last_name": "User008",
"main_phone": "+438843553",
"reference": "ab0042",
"status": 0
},
{
"display_name": "TestO",
"first_name": "TestO",
"id": 12286,
"is_public": 0,
"last_name": null,
"main_phone": "+5321235135",
"reference": null,
"status": 0
},
{
"display_name": "TestP",
"first_name": "TestP",
"id": 12287,
"is_public": 0,
"last_name": null,
"main_phone": "+53135511351",
"reference": null,
"status": 0
}
]
}
Contact Groups
List of contacts (paginated)
curl --header "Authorization: Bearer [YOUR NEW TOKEN]" \
https://sms.jooksms.com/api/v1/contact_group/
// TBD
Returns:
{
"result": "ok",
"meta": {
"pagination": {
"count": 3,
"current_page": 1,
"links": [],
"per_page": 15,
"total": 3,
"total_pages": 1
}
},
"data": [
{
"id": 6,
"name": "Group 001"
},
{
"id": 5,
"name": "Group 002"
},
{
"id": 4,
"name": "Group VIP"
}
]
}
SMS Search
Search SMS messages
curl -X POST -H "Authorization: Bearer [YOUR NEW TOKEN]" \
-d '
{
"number": "+1352225566",
"from_date": "2018/03/01 00:00 +5000",
"to_date": "2018/03/15 23:59 +5000",
"query": "offer"
}' \
https://sms.jooksms.com/api/v1/sms/search/messages
\\ TBD
Returns:
{
"data": [
{
"id": 210337,
"external_id": null,
"direction": "sending",
"status": "sent",
"number": "+135225566",
"content": "Here is a new offer",
"created": "2017-03-07T15:59:48+00:00",
"updated": "2017-05-31T23:25:55+00:00"
}
],
"meta": {
"pagination": {
"total": 1,
"count": 1,
"per_page": 15,
"current_page": 1,
"total_pages": 1,
"links": []
}
},
"result": "ok"
}
Parameters:
| Parameter | Required | Description |
|---|---|---|
| number | No | The phone number that you want to look messages for/from. Remember to include + and the country code |
| from_date | No | The date from which the message must start. Format yyy/mm/dd hh:mm t |
| to_date | No | The date up to which the message must end. Format yyy/mm/dd hh:mm t |
| query | No | A string to search inside the content of the messages |
Note: You must at least add one of the parameters.