API系列(一):SMS API
简介
你们好,辛苦工作的朋友们!
本文有用之处:
以简约,直白的方式,给未曾接触过短信接口的朋友们,展示一个大概的思路。
本次介绍的是一款来自狮子王国肯尼亚的短信接口方案。由Xcobean 公司提供。
主要使用的技术以REST API风格的接口形式,实现了通讯录(联系人组)管理,联系人管理,短信管理以及WhatsApp短消息管理。
下图是他们的商业版图,可见该公司业务还是挺全面的。
本文将按照四个章节,依次对各个接口代码进行复制黏贴展示。本文更像是一篇笔记,当然有用之处也在文章开头写了。敬请阅读。欢迎新老朋友指点。花钱找这家公司注册账户,购买api之后,得到两个东西,一个是你的api 站点url,另一个是的token。
一、 CONTACT GROUPS API
Xcobean SMS Contact Groups API 允许您管理由唯一随机 ID 标识的联系人组。 使用此 ID 创建、查看、更新或删除组。
1. 总概
全部形式 保持统一:
url: https url;
method: GET, POST,PACH,DELETE
header 头部由认证Authorization,内容类型Content-Type,接受类型 Accept。
Authorization 采用 token。在使用Bearer令牌的身份验证流程中,客户端(例如 Web 应用程序或移动应用程序)通过向身份提供者(例如 Google、Facebook 或其他身份提供者)发送请求来获取访问令牌。一旦获取到访问令牌,客户端将在发送每个 API 请求时将该令牌作为 “Authorization” 请求标头的一部分发送到 API。···
content: POST json 请求体
return: 请求返回的json 体
2. Create a group
创建联系人分组,以方便之后批量发送营销信息,像微信一样给联系人上标签,发信息只发给有标签的人。
url: https://sms.xcobean.com/api/v3/contacts
method: post
header:
'Authorization: Bearer ${你的token}'
'Content-Type: application/json'
'Accept: application/json'
content:
{
"name": "Mombasa"
}
return:
{
"status": "success",
"message": "Contact group was successfully added",
"data": {
"name": "Mombasa",
"uid": "645e4dd27b55a"
}
}
3. View a group
查看分组信息。
url: https://sms.xcobean.com/api/v3/contacts/{group_id}/show/
method: post
parameter: group_id 645e38f3e7e9d
header:
'Authorization: Bearer 8|FMwObDuDLPSAE6YkCB9p1cUjnIs61kECKjVmz111'
'Content-Type: application/json'
'Accept: application/json'
return:
{
"status": "success",
"message": null,
"data": {
"uid": "645e4dd27b55a",
"name": "Mombasa"
}
}
4. Update a group
更新分组,使用patch。
url: https://sms.xcobean.com/api/v3/contacts/{group_id}
method: patch
content:
{
"name": "Kwale"
}
return:
{
"status": "success",
"message": "Contact group was successfully updated",
"data": {
"name": "Kwale",
"uid": "645e4dd27b55a"
}
}
5. Delete a group
删除一个分组。
url: https://sms.xcobean.com/api/v3/contacts/{group_id}
method: delete
parameter:
group_id: 645e38f3e7e9d
return:
{
"status": "error",
"message": "Attempt to read property \"id\" on null"
}
6. View all groups
查看所有的分组。
url: https://sms.xcobean.com/api/v3/contacts/{group_id}
method: get
return:
{
"status": "success",
"message": null,
"data": {
"current_page": 1,
"data": [
{
"uid": "645e4f1be9ad2",
"name": "Kilifi"
}
],
"first_page_url": "https://sms.xcobean.com/api/v3/contacts?page=1",
"from": 1,
"last_page": 1,
"last_page_url": "https://sms.xcobean.com/api/v3/contacts?page=1",
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://sms.xcobean.com/api/v3/contacts?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Next »",
"active": false
}
],
"next_page_url": null,
"path": "https://sms.xcobean.com/api/v3/contacts",
"per_page": 25,
"prev_page_url": null,
"to": 1,
"total": 1
}
}
二、 CONTACTS API
1. 总概
Xcobean SMS Contacts API 可帮助您管理由唯一随机 ID 标识的联系人。 使用此 ID,您可以创建、查看、更新或删除联系人。 此 API 用作客户特定联系人的集合,允许您对它们进行分组并分配自定义值,您稍后可以在发送 SMS 模板消息时使用这些值。
Contacts API 使用 HTTP 动词和 RESTful 端点结构以及用作 API 授权的访问密钥。 使用 UTF-8 编码和 URL 编码值将请求和响应有效负载格式化为 JSON。
2. Create a contact
url: https://sms.xcobean.com/api/v3/contacts/{group_id}/store
method: POST
parameter:
group_id: 645e38f3e7e9d
content:
{
"phone": "25420342277",
"first_name": "Tana",
"last_name": "River"
}
return:
{
"status": "success",
"message": "Contact was successfully added",
"data": {
"customer_id": 7,
"group_id": 6,
"phone": 25420317778,
"first_name": "Tana",
"last_name": "River",
"uid": "645e5a0e3833b",
"status": "subscribe",
"updated_at": "2023-05-12T15:23:58.000000Z",
"created_at": "2023-05-12T15:23:58.000000Z",
"id": 3
}
}
3. View a contact
url: https://sms.xcobean.com/api/v3/contacts/{{group_id}}/search/{{uid}}
method: POST
return:
{
"status": "success",
"message": null,
"data": {
"uid": "645e5a0e3833b",
"phone": "25420641216",
"first_name": "Taita",
"last_name": "Taveta"
}
}
4. Update a contact
url: https://sms.xcobean.com/api/v3/contacts/{group_id}/update/{uid}
method: PATCH
content:
{
"phone":"25420343715"
}
return:
{
"status": "success",
"message": "Contact was successfully updated",
"data": {
"id": 3,
"uid": "645e5a0e3833b",
"customer_id": 7,
"group_id": 6,
"phone": 25420558565,
"status": "subscribe",
"first_name": "Garissa",
"last_name": "Wajir",
"email": null,
"username": null,
"company": null,
"address": null,
"birth_date": null,
"anniversary_date": null,
"created_at": "2023-05-12T15:23:58.000000Z",
"updated_at": "2023-05-12T15:23:58.000000Z"
}
}
5. View all contacts in group
url: https://sms.xcobean.com/api/v3/contacts/{group_id}/all
method: POST
return:
{
"status": "success",
"message": null,
"data": {
"current_page": 1,
"data": [
{
"uid": "645e59a786720",
"phone": 25420552298,
"first_name": "Mandera",
"last_name": "Marsabit"
},
{
"uid": "645e59b3716d6",
"phone": 25420550493,
"first_name": "Isiolo",
"last_name": "Meru"
},
{
"uid": "645e5a0e3833b",
"phone": 25420344037,
"first_name": "Tharaka",
"last_name": "Nithi"
}
],
"first_page_url": "https://sms.xcobean.com/api/v3/contacts/645e56be3c6d2/all?page=1",
"from": 1,
"last_page": 1,
"last_page_url": "https://sms.xcobean.com/api/v3/contacts/645e56be3c6d2/all?page=1",
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://sms.xcobean.com/api/v3/contacts/645e56be3c6d2/all?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Next »",
"active": false
}
],
"next_page_url": null,
"path": "https://sms.xcobean.com/api/v3/contacts/645e56be3c6d2/all",
"per_page": 25,
"prev_page_url": null,
"to": 3,
"total": 3
}
}
6. Delete a contact
url: https://sms.xcobean.com/api/v3/contacts/{group_id}/delete/{uid}
method: delete
return:
{
"status": "success",
"message": "Contact was successfully deleted",
"data": null
}
三、 SMS API
1. 总概
Xcobean SMS SMS API 允许您通过 REST API 向世界上任何国家/地区发送和接收 SMS 消息。 每条消息都由一个唯一的随机 ID 标识,以便用户始终可以使用给定的端点检查消息的状态。
2. Send outbound SMS
url: https://sms.xcobean.com/api/v3/sms/send
method: POST
content:
{
"recipient": "25420829085",
"sender_id": "[Test]",
"type": "plain",
"message": "Dear user"
}
return:
{
"status": "error",
"message": "No sending server available for your subscribed plan"
}
3. View an SMS
url: https://sms.xcobean.com/api/v3/sms/{uid}
method: GET
parameter:
uid: 645e5a0e3833b
content:
{
"recipient": "25420550331",
"sender_id": "[Test]",
"type": "plain",
"message": "Dear user"
}
return:
{
"status": "error",
"message": "No query results for model [App\\Models\\Reports] 645e59b3716d6"
}
4. View all messages
url: https://sms.xcobean.com/api/v3/sms/
method: GET
return:
{
"status": "success",
"message": null,
"data": {
"current_page": 1,
"data": [],
"first_page_url": "https://sms.xcobean.com/api/v3/sms?page=1",
"from": null,
"last_page": 1,
"last_page_url": "https://sms.xcobean.com/api/v3/sms?page=1",
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://sms.xcobean.com/api/v3/sms?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Next »",
"active": false
}
],
"next_page_url": null,
"path": "https://sms.xcobean.com/api/v3/sms",
"per_page": 25,
"prev_page_url": null,
"to": null,
"total": 0
}
}
四、 WHATSAPP API
1. 总概
Xcobean SMS SMS API 允许您通过 REST API 向世界上任何国家/地区发送和接收 SMS 消息。 每条消息都由一个唯一的随机 ID 标识,以便用户始终可以使用给定的端点检查消息的状态。
API Endpoint
2. Send outbound SMS
url: https://sms.xcobean.com/api/v3/sms/send
method: POST
content:
{
"recipient": "25420555259",
"sender_id": "YourName",
"type": "whatsapp",
"message": "This is a test message"
}
return:
{
"status": "error",
"message": "No sending server available for your subscribed plan"
}
3. View an SMS
url: https://sms.xcobean.com/api/v3/sms/{uid}
method: GET
parameter:
uid: 645e5a0e3833b
return:
{
"status": "success",
"message": null,
"data": {
"current_page": 1,
"data": [],
"first_page_url": "https://sms.xcobean.com/api/v3/sms?page=1",
"from": null,
"last_page": 1,
"last_page_url": "https://sms.xcobean.com/api/v3/sms?page=1",
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://sms.xcobean.com/api/v3/sms?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Next »",
"active": false
}
],
"next_page_url": null,
"path": "https://sms.xcobean.com/api/v3/sms",
"per_page": 25,
"prev_page_url": null,
"to": null,
"total": 0
}
}
4. View all messages
url: https://sms.xcobean.com/api/v3/sms/
method: GET
parameter:
uid: 645e5a0e3833b
return:
{
"status": "success",
"message": null,
"data": {
"current_page": 1,
"data": [],
"first_page_url": "https://sms.xcobean.com/api/v3/sms?page=1",
"from": null,
"last_page": 1,
"last_page_url": "https://sms.xcobean.com/api/v3/sms?page=1",
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://sms.xcobean.com/api/v3/sms?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Next »",
"active": false
}
],
"next_page_url": null,
"path": "https://sms.xcobean.com/api/v3/sms",
"per_page": 25,
"prev_page_url": null,
"to": null,
"total": 0
}
}
总结:
总共黏贴了四个章节的指南,
1.contact groups api
2.contacts api
3.sms api
4.whatsapp api
《登高》是一首鼓励程序员小白的古诗,全诗如下:
飞流直下三千尺,
疑似骑鹤腾空泄。
千峰万壑路不定,
迷花倚石忽已暝。
熊咆龙吟殷岩泉,
栗深林兮惊层巅。
云横秦岭家何在?
雪拥蓝关马不前。
这首诗借用了自然界的壮丽景色,鼓励程序员小白要像登高者一样,勇往直前,迎接新的挑战。即使面对千峰万壑,也要坚定地迈出脚步,探索前行的道路。同时,诗中也表达了对困难的正视和克服困难的勇气。
古人在写诗时常常以自然景观来寄托情感和寓意,这种表达方式也可以激励现代程序员面对技术挑战时的勇气和决心。