گفتگوها
اپراتورها
راهنمای استفاده
گفتینو این امکان را به شما می دهد که توسط API ارایه شده، به بخش هایی از سامانه خود دسترسی و از آنها برای مدیریت گفتگوها و کاربران استفاده نمایید. (به مرور امکانات موجود در API توسعه خواهد یافت)
احراز هویت :
برای ارسال و دریافت اطلاعات در API گفتینو در شناسایی و اعتبار سنجی حساب کاربری، از پارامتر goftino-key استفاده می شود. در تنظیمات سامانه، بخش api را برای دریافت این پارامتر بررسی کنید.
ارسال Header :
برای ایجاد هر نوع درخواست در API گفتینو، از نمونه Header ارایه شده، همراه با مقادیر مورد نیاز هر متد ، استفاده نمایید.
محدودیت درخواست :
جهت حفظ پایداری و امنیت سرویس، تعداد ارسال لحظه ای درخواست ها به API گفتینو محدودیت دارد و طبق سیاست استفاده منصفانه ارایه خواهد شد.
Headers
Content-Type: application/json goftino-key: YOUR-API-KEY
chats
GET
https://api.goftino.com/v1/chats
از این متد برای دریافت لیست کل گفتگوها استفاده می شود.
داده های ارسالی : (Query string)
limit
(string)
تعداد گفتگو در لیست خروجی (حداکثر 50)
page
(string)
شماره صفحه لیست گفتگوها
operator_id
(string)
جستجو بر اساس گفتگوهای یک اپراتور خاص
status
(string)
جستجو بر اساس وضعیت باز یا بسته بودن گفتگو (open | closed)
has_owner
(boolean)
جستجو در گفتگوهای باز بر اساس گفتگوهای بدون اپراتور پاسخگو (در حال انتظار) یا دارای پاسخگو
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
chats
(array[object])
chat_id
(string) - گفتگوی مربوطه id
unread_messages
(number) - تعداد پیام های خوانده نشده در سمت اپراتورها
chat_status
(string) - وضعیت گفتگو که باز یا بسته است
current_owner
(array[string]) - لیست id اپراتورهای در حال پاسخ این گفتگو
all_operators
(array[string]) - لیست id اپراتورهای قبلی پاسخگو در این گفتگو
user_id
(string) - id کاربر مربوطه
user_name
(string) - نام کاربر مربوطه
last_message
(array[object]) - لیست پیام ها
sender
(object)
from
(string) - ارسال کننده پیام که operator یا user است
id
(string) - id کاربر یا اپراتور مربوطه
date
(string) - تاریخ ارسال پیام
content
(string) - محتوای پیام
type
(string) - نوع پیام شامل text, voice, file, start_form, delay_from, offline_form, question_answer
fields
(array[object]) - در صورتی که پیام از نوع فرم باشد، لیست فیلد ها نمایش داده می شود
label
(string) - عنوان فیلد
value
(string) - محتوای فیلد
page
(number) - شماره صفحه
نمونه درخواست
curl --request GET 'https://api.goftino.com/v1/chats' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY'
نمونه پاسخ موفق200 OK
{
"status": "success",
"data": {
"chats": [
{
"chat_id": "61225d8fc0925903200fbc74",
"chat_status": "open",
"current_owner": ["607013e5fc6a0b37b4007c6d"],
"all_operators": [ ],
"unread_messages": 1,
"user_id": "61225d87c0925903200fbc73b0423a29b1330017ea8498167e9a7c024d05c3c8",
"user_name": "Ali",
"last_message": {
"sender": {
"from": "operator",
"id": "607013e5fc6a0b37b4007c6d"
},
"date": "2021-09-05 21:38:03",
"content": "How can I help you?",
"type": "text"
}
}
],
"page": 1
}
}
chat_data
Format : YYYY-MM-DD یا YYYY-MM-DDTHH:mm:ss
Format : YYYY-MM-DD یا YYYY-MM-DDTHH:mm:ss
GET
https://api.goftino.com/v1/chat_data
از این متد برای دریافت اطلاعات و پیام های یک گفتگو استفاده می شود.
داده های ارسالی : (Query string)
chat_id
(string)اجباری
id گفتگوی مورد نظر
from_date
(string)
جستجو بر اساس پیام تبادل شده از تاریخ مورد نظرFormat : YYYY-MM-DD یا YYYY-MM-DDTHH:mm:ss
to_date
(string)
جستجو بر اساس پیام تبادل شده تا تاریخ مورد نظرFormat : YYYY-MM-DD یا YYYY-MM-DDTHH:mm:ss
limit
(string)
تعداد پیام در لیست خروجی (حداکثر 50)
page
(string)
شماره صفحه لیست پیام ها
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
messages_count
(number) - تعداد کل پیام های این گفتگو
chat_status
(string) - وضعیت گفتگو که باز یا بسته است
current_owner
(array[string]) - لیست id اپراتورهای در حال پاسخ این گفتگو
all_operators
(array[string]) - لیست id اپراتورهای قبلی پاسخگو در این گفتگو
user_id
(string) - id کاربر مربوطه
messages
(array[object]) - لیست پیام ها
message_id
(string) - id پیام مربوطه
sender
(object)
from
(string) - ارسال کننده پیام که operator یا user است
id
(string) - id کاربر یا اپراتور مربوطه
date
(string) - تاریخ ارسال پیام
content
(string) - محتوای پیام
type
(string) - نوع پیام شامل text, voice, file, start_form, delay_from, offline_form, question_answer
is_seen
(boolean) - دیده شدن پیام توسط مخاطب
reply_to
(string) - در پاسخ به این پیام
fields
(array[object]) - در صورتی که پیام از نوع فرم باشد، لیست فیلد ها نمایش داده می شود
label
(string) - عنوان فیلد
value
(string) - محتوای فیلد
نمونه درخواست
curl --request GET 'https://api.goftino.com/v1/chat_data?chat_id=61031e563060c5ffe08f8777&from_date=1402-01-05T17:35:07' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY'
نمونه پاسخ موفق200 OK
{
"status": "success",
"data": {
"messages_count": 1,
"chat_status": "open",
"current_owner": ["607013e5fc6a0b37b4007c6d"],
"all_operators": [ ],
"chat_id": "61225d8fc0925903200fbc74",
"user_id": "61225d87c0925903200fbc73b0423a29b1330017ea8498167e9a7c024d05c3c8",
"messages": [
{
"message_id": "5d225d8fc0925903200fb5e1",
"sender": {
"from": "operator",
"id": "607013e5fc6a0b37b4007c6d"
},
"date": "2021-09-05 21:38:03",
"content": "How can I help you?",
"type": "text"
"is_seen": true
"reply_to": "please help me"
}
]
}
}
send_message
POST
https://api.goftino.com/v1/send_message
از این متد برای ارسال پیام متنی از اپراتور به کاربر استفاده می شود.
داده های ارسالی :
chat_id
(string)اجباری
id گفتگوی مورد نظر
operator_id
(string)اجباری
id اپراتور ارسال کننده پیام
message
(string)اجباری
متن پیام ارسالی
reply_id
(string)
id پیام مورد پاسخ به آن
افزودن دکمه در محتوای پیام
در پارامتر message ارسالی، امکان درج دکمه با واکنش های مختلف به شکل زیر فراهم است :
باز کردن لینک
[button title="title of link" action="open_url" data="https://site.com"]
نمایش یک متن
[button title="more info" action="show_message" data="this text will show after click"]
انتقال گفتگو
[button title="connect to operator" action="assign" data="61225d8fc0925903200fbc74" message_after_click="this text will show after click"]
data : می توانید id یک اپراتور یا چند اپراتور (با , از هم جدا شوند) یا عبارت "all_operators" را قرار دهید.
فراخوانی یک رویداد جاوا اسکریپت
[button title="show card" action="js_event" data="shopping-card-setting"
message_after_click="this text will show after click"]
message_after_click :
یک پارامتر اختیاری است که برای نمایش یک متن ساده بعد از کلیک کاربر روی آن گزینه استفاده می شود.
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
message_id
(string)
id پیام ارسالی
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/send_message' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"message":"hello,it is a message...","chat_id":"61031e563060c5ffe08f8777","operator_id":"609bee1fb5f9aa2640e9fd57"}'
Body
{
"chat_id": "61031e563060c5ffe08f8777",
"operator_id": "609bee1fb5f9aa2640e9fd57",
"message": "hello,it is a message..."
}
نمونه پاسخ موفق200 OK
{
"status": "success"
"data": {
"message_id": "61031e563060c5ffe08f21ef"
}
}
send_message_from_user
POST
https://api.goftino.com/v1/send_message_from_user
از این متد برای ارسال پیام متنی از کاربر به اپراتورها استفاده می شود.
داده های ارسالی :
chat_id
(string)اجباری
id گفتگوی مورد نظر
message
(string)اجباری
متن پیام ارسالی
reply_id
(string)
id پیام مورد پاسخ به آن
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
message_id
(string)
id پیام ارسالی
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/send_message_from_user' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"message":"hello,it is a message...","chat_id":"61031e563060c5ffe08f8777"}'
Body
{
"chat_id": "61031e563060c5ffe08f8777",
"message": "hello,it is a message..."
}
نمونه پاسخ موفق200 OK
{
"status": "success"
"data": {
"message_id": "61031e563060c5ffe08f32d3"
}
}
send_file
POST
https://api.goftino.com/v1/send_file
از این متد برای ارسال فایل از اپراتور به کاربر استفاده می شود.
داده های ارسالی : (Query string)
chat_id
(string)اجباری
id گفتگوی مورد نظر
operator_id
(string)اجباری
id اپراتور ارسال کننده
file
(string)اجباری
فایل ارسالی (بصورت form-data)
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
message_id
(string)
id پیام ارسالی
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/send_file?chat_id=61031e563060c5ffe08f877c&operator_id=61031e563060c5ffe08f8de1' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --form 'file=@image.jpg'
Body
{
"file": "image.jpg"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
"data": {
"message_id": "61031e563060c5ffe08f21f6"
}
}
send_voice
POST
https://api.goftino.com/v1/send_voice
از این متد برای ارسال فایل صوتی از اپراتور به کاربر استفاده می شود.
داده های ارسالی : (Query string)
chat_id
(string)اجباری
id گفتگوی مورد نظر
operator_id
(string)اجباری
id اپراتور ارسال کننده
duration
(string)اجباری
مدت زمان فایل صوتی بر حسب ثانیه
file
(string)اجباری
فایل صوتی با پسوند ogg یا mp3 (بصورت form-data)
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
message_id
(string)
id پیام ارسالی
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/send_voice?chat_id=61031e563060c5ffe08f877c&operator_id=61031e563060c5ffe08f8de1&duration=15' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --form 'file=@voice.ogg'
Body
{
"file": "voice.ogg"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
"data": {
"message_id": "61031e563060c5ffe08f21f6"
}
}
operator_typing
POST
https://api.goftino.com/v1/operator_typing
از این متد برای ارسال وضعیت در حال نوشتن متن روی از اپراتور به کاربر استفاده می شود.
داده های ارسالی :
chat_id
(string)اجباری
id گفتگوی مورد نظر
operator_id
(string)اجباری
id اپراتور در حال نوشتن
typing_status
(string)اجباری
مقدار true یا false
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/operator_typing' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"chat_id":"61031e563060c5ffe08f8777","operator_id":"61031e563060c5ffe08f8ce4", "typing_status":"true"}'
Body
{
"chat_id": "61031e563060c5ffe08f8777",
"operator_id": "61031e563060c5ffe08f8ce4",
"typing_status": "true"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
}
close_chat
POST
https://api.goftino.com/v1/close_chat
از این متد برای بستن گفتگو استفاده می شود.
داده های ارسالی :
chat_id
(string)اجباری
id گفتگوی مورد نظر
operator_id
(string)اجباری
id اپراتور مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/close_chat' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"chat_id":"61031e563060c5ffe08f8777","operator_id":"609bee1fb5f9aa2640e9fd57"}'
Body
{
"chat_id": "61031e563060c5ffe08f8777",
"operator_id": "609bee1fb5f9aa2640e9fd57"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
}
transfer_chat
POST
https://api.goftino.com/v1/transfer_chat
از این متد برای انتقال گفتگو استفاده می شود. در نظر داشته باشید، امکان انتقال یک مکالمه فقط در صورت باز بودن وضعیت آن گفتگو میسر خواهد بود. همچنین شخص ارسال کننده و گیرنده گفتگو باید نقش اپراتور هم داشته باشند.
داده های ارسالی :
chat_id
(string)اجباری
id گفتگوی مورد نظر
from_operator
(string)اجباری
id اپراتور انتقال دهنده
to_operator
(string)اجباری
id اپراتور انتقال گیرنده
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/transfer_chat' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"chat_id":"61031e563060c5ffe08f8777","from_operator":"609bee1fb5f9aa2640e9fd57","to_operator":"619bee1fb579a82640e9e118"}'
Body
{
"chat_id": "61031e563060c5ffe08f8777",
"from_operator": "609bee1fb5f9aa2640e9fd57",
"to_operator": "619bee1fb579a82640e9e118"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
}
unassign_chat
POST
https://api.goftino.com/v1/unassign_chat
از این متد برای برگشت یک مکالمه از لیست "گفتگوهای من" یا "گفتگوهای دیگر" به لیست "گفتگوهای در حال انتظار" استفاده می شود. در نظر داشته باشید، این امکان در صورت باز بودن وضعیت آن گفتگو میسر خواهد بود. همچنین شخص اقدام کننده باید نقش اپراتور داشته باشد.
داده های ارسالی :
chat_id
(string)اجباری
id گفتگوی مورد نظر
from_operator
(string)اجباری
id اپراتور اقدام کننده
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/unassign_chat' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"chat_id":"61031e563060c5ffe08f8777","from_operator":"609bee1fb5f9aa2640e9fd57"}'
Body
{
"chat_id": "61031e563060c5ffe08f8777",
"from_operator": "609bee1fb5f9aa2640e9fd57"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
}
edit_message
GET
https://api.goftino.com/v1/edit_message
از این متد برای دریافت تاریخچه ویرایش های یک پیام استفاده می شود.
داده های ارسالی : (Query string)
message_id
(string)اجباری
id پیام مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
messages
(array)
نمونه درخواست
curl --request GET 'https://api.goftino.com/v1/edit_message?message_id=61031e563060c3ffe08f2cc4' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY'
نمونه پاسخ موفق200 OK
{
"status": "success",
"data": {
"messages": [
"first text",
"the first text",
"the first text message"
]
}
}
edit_message
POST
https://api.goftino.com/v1/edit_message
از این متد برای ویرایش یک پیام استفاده می شود.
داده های ارسالی :
message
(string)اجباری
متن پیام ارسالی
message_id
(string)اجباری
id پیام مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/edit_message' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"message":"new text","message_id":"61031e563060c5ffe08f841c3"}'
Body
{
"message": "new text",
"message_id": "61031e563060c5ffe08f841c3"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
}
send_poll
POST
https://api.goftino.com/v1/send_poll
از این متد برای ارسال نظرسنجی به مخاطب استفاده می شود.
داده های ارسالی :
chat_id
(string)اجباری
id گفتگوی مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/send_poll' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"chat_id":"61031e563060c5ffe08f83edf"}'
Body
{
"chat_id": "61031e563060c5ffe08f83edf"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
}
user_unread_messages
GET
https://api.goftino.com/v1/user_unread_messages
از این متد برای دریافت پیام های خوانده نشده کاربر استفاده می شود. کافیست تنها یکی از 2 پارارمتر chat_id یا user_id را ارسال کنید.
داده های ارسالی : (Query string)
chat_id
(string)
id گفتگوی مورد نظر
user_id
(string)
id کاربر مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) -
در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
messages_count
(number) - تعداد پیام های خوانده نشده کاربر
chat_status
(string) - وضعیت گفتگو که باز یا بسته است
chat_id
(string) - id گفتگوی مربوطه
user_id
(string) - id کاربر مربوطه
messages
(array[object]) - لیست پیام ها
sender
(object)
from
(string) - ارسال کننده پیام که operator یا user است
id
(string) - id کاربر یا اپراتور مربوطه
date
(string) - تاریخ ارسال پیام
content
(string) - محتوای پیام
type
(string) - نوع پیام شامل text, voice, file
نمونه درخواست
curl --request GET 'https://api.goftino.com/v1/user_unread_messages?chat_id=61031e563060c5ffe08f8777' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY'
نمونه پاسخ موفق200 OK
{
"status": "success",
"data": {
"messages_count": 1,
"chat_status": "open",
"chat_id": "61225d8fc0925903200fbc74",
"user_id": "61225d87c0925903200fbc73b0423a29b1330017ea8498167e9a7c024d05c3c8",
"messages": [
{
"sender": {
"from": "operator",
"id": "607013e5fc6a0b37b4007c6d"
},
"date": "2021-09-05 21:38:03",
"content": "How can I help you?",
"type": "text"
}
]
}
}
create_chat
POST
https://api.goftino.com/v1/create_chat
از این متد برای ایجاد یک گفتگوی جدید در سامانه استفاده می شود. (همچنین یک عدد از اعتبار گفتگوهای سامانه شما کسر خواهد شد)
داده های ارسالی :
message
(string)اجباری
متن پیام ارسالی از طرف مخاطب
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
chat_id
گفتگوی مربوطه id
user_id
کاربر مربوطه id
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/create_chat' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"message":"hello, please help me..."}'
Body
{
"message": "hello, please help me..."
}
نمونه پاسخ موفق200 OK
{
"status": "success"
"data": {
"chat_id": "61031e563060c5ffe08f8777",
"user_id": "61225d87c0925903200fbc73b0423a29b1330017ea8498167e9a7c024d05c3c8"
}
}
remove_chat
POST
https://api.goftino.com/v1/remove_chat
از این متد برای حذف کامل یک گفتگو در سامانه استفاده می شود.
داده های ارسالی :
chat_id
(string)اجباری
گفتگوی مورد نظر id
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/remove_chat' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"chat_id":"61031e563060c5ffe08f8777"}'
Body
{
"chat_id": "61031e563060c5ffe08f8777"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
}
user_data
GET
https://api.goftino.com/v1/user_data
از این متد برای دریافت اطلاعات کاربر استفاده می شود. کافیست تنها یکی از 2 پارارمتر chat_id یا user_id را ارسال کنید.
داده های ارسالی : (Query string)
chat_id
(string)
id گفتگوی مورد نظر
user_id
(string)
id کاربر مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
avatar
(string) - تصویر کاربر
name
(string) - نام
email
(string) - ایمیل
phone
(string) - تلفن
description
(string) - توضیحات جانبی
tags
(array[string]) - لیست برچسب ها
ip
(string) - آی پی
location
(string) - کشور
browser
(string) - مرورگر کاربر
os
(string) - سیستم عامل کاربر
is_banned
(boolean) - وضعیت مسدودی کاربر
last_url
(string) - آدرس آخرین صفحه بازدید شده کاربر
last_visit
(string) - زمان آخرین بازدید کاربر
first_visit
(string) - زمان اولین بازدید کاربر
page_view
(string) - تعداد بازدید صفحات
chat_id
(string) - id گفتگوی کاربر
user_id
(string) - id کاربر مربوطه
نمونه درخواست
curl --request GET 'https://api.goftino.com/v1/user_data?chat_id=61031e563060c5ffe08f8777' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY'
نمونه پاسخ موفق200 OK
{
"status": "success",
"data": {
"avatar": "",
"name": "ahmad",
"email": "ahmad@mysite.com",
"phone": "09123456789",
"description": "",
"tags": [ "tag1" ],
"ip": "192.168.12.20",
"location": "Iran",
"browser": "Chrome 72.0.3626",
"os": "Windows 10",
"is_banned": false,
"last_url": "https://www.goftino.com/help",
"last_visit": "2021-09-05 21:38:03",
"first_visit": "2021-09-03 17:52:12",
"page_view": "25",
"chat_id": "61031e563060c5ffe08f8777",
"user_id": "61225d87c0925903200fbc73b0423a29b1330017ea8498167e9a7c024d05c3c8"
}
}
user_data
POST
https://api.goftino.com/v1/user_data
از این متد برای ارسال اطلاعات کاربر به گفتینو استفاده می شود.
داده های ارسالی :
user_id
(string)اجباری
id کاربر مورد نظر
name
(string)اختیاری
نام کاربر
phone
(string)اختیاری
شماره تلفن کاربر
email
(string)اختیاری
ایمیل کاربر
avatar
(string)اختیاری
تصویر کاربر
description
(string)اختیاری
توضیحات جانبی کاربر
tags
(array)اختیاری
برچسب
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/user_data' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"user_id":"60fb3f4f0f1063509260a5fa0d613dbfc084a0c3ce7e4e275f4d2035975f3f03","name":"Ali Rahimi","phone":"09123456789","avatar":"https://www.mysite.com/user.jpg","tags":["tag1","tag2"]}'
Body
{
"user_id": "60fb3f4f0f1063509260a5fa0d613dbfc084a0c3ce7e4e275f4d2035975f3f03",
"name": "Ali Rahimi",
"phone": "09123456789",
"avatar": "https://www.mysite.com/user.jpg",
"tags": ["tag1","tag2"]
}
نمونه پاسخ موفق200 OK
{
"status": "success"
}
ban_user
POST
https://api.goftino.com/v1/ban_user
از این متد برای مسدود کردن کاربر استفاده می شود. کافیست تنها یکی از 2 پارارمتر chat_id یا user_id را ارسال کنید.
داده های ارسالی :
operator_id
(string)اجباری
id اپراتور مورد نظر
chat_id
(string)
id گفتگوی مورد نظر
user_id
(string)
id کاربر مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --request POST 'https://api.goftino.com/v1/ban_user' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY' \ --data '{"user_id":"60fb3f4f0f1063509260a5fa0d613dbfc084a0c3ce7e4e275f4d2035975f3f03"}'
Body
{
"user_id": "60fb3f4f0f1063509260a5fa0d613dbfc084a0c3ce7e4e275f4d2035975f3f03"
}
نمونه پاسخ موفق200 OK
{
"status": "success"
}
user_visited_pages
GET
https://api.goftino.com/v1/user_visited_pages
از این متد برای دریافت لیست صفحات بازدید شده کاربر استفاده می شود.
داده های ارسالی : (Query string)
user_id
(string)
id کاربر مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
pages
(array[object])
url
(string) - آدرس صفحه بازدید شده
date
(string) - تاریخ بازدید صفحه
time_on_page
(number) - مدت زمان حضور در صفحه بر حسب ثانیه
نمونه درخواست
curl --request GET 'https://api.goftino.com/v1/user_visited_pages?user_id=60fb3f4f0f1063509260a5fa0d613dbfc084a0c3ce7e4e275f4d2035975f3f03' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY'
نمونه پاسخ موفق200 OK
{
"status": "success",
"data": {
"pages": [
{
"url": "https://mysite.com/product",
"date": "2023-09-05 21:38:03",
"time_on_page": 45
},
{
"url": "https://mysite.com/product/page1",
"date": "2023-09-05 21:45:03",
"time_on_page": 120
},
]
}
}
operators
GET
https://api.goftino.com/v1/operators
از این متد برای دریافت لیست اپراتورها استفاده می شود.
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
operators
(array[object])
avatar
(string) - تصویر کاربر
name
(string) - نام اپراتور
email
(string) - ایمیل اپراتور
is_online
(boolean) - وضعیت آنلاین بودن اپراتور
operator_id
(string) - id اپراتور مربوطه
نمونه درخواست
curl --request GET 'https://api.goftino.com/v1/operators' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY'
نمونه پاسخ موفق200 OK
{
"status": "success",
"data": {
"operators": [
{
"avatar": "https://cdn.goftino.com/profile/avatar.png",
"name": "ali",
"email": "ali@email.com",
"is_online": true,
"operator_id": "61031e563060c5ffe08f2525"
}
]
}
}
operator_data
GET
https://api.goftino.com/v1/operator_data
از این متد برای دریافت اطلاعات کاربر استفاده می شود. کافیست تنها یکی از 2 پارارمتر email یا operator_id را ارسال کنید.
داده های ارسالی : (Query string)
email
(string)
ایمیل اپراتور مورد نظر
operator_id
(string)
id اپراتور مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
data
(object)
avatar
(string) - تصویر کاربر
name
(string) - نام اپراتور
email
(string) - ایمیل اپراتور
is_online
(boolean) - وضعیت آنلاین بودن اپراتور
operator_id
(string) - id اپراتور مربوطه
نمونه درخواست
curl --request GET 'https://api.goftino.com/v1/operator_data?email=ali@email.com' \ --header 'Content-Type: application/json' \ --header 'goftino-key: YOUR-API-KEY'
نمونه پاسخ موفق200 OK
{
"status": "success",
"data": {
"avatar": "https://cdn.goftino.com/profile/avatar.png",
"name": "ali",
"email": "ali@email.com",
"is_online": true,
"operator_id": "61031e563060c5ffe08f2525"
}
}
Webhook
برای دریافت رویداد ها از گفتینو، هنگام دریافت یا ارسال پیام ها و
... نیاز است در سمت خود فرآیندی ایجاد کرده تا اطلاعات مربوطه را دریافت و از آنها استفاده نمایید.
اطلاعات مورد نظر از طریق درخواست http با متد POST و با فرمت JSON به آدرس وب هوک ثبت شده شما در تنظیمات سامانه فرستاده می شود.
در صورت بروز خطای مکرر در سمت آدرس webhook شما، ارسال اطلاعات بطور موقت غیرفعال خواهد شد.
در صورت بروز خطای مکرر در سمت آدرس webhook شما، ارسال اطلاعات بطور موقت غیرفعال خواهد شد.
رویداد های دریافتی :
new_message
یک پیام در سامانه از سوی کاربر یا اپراتور ارسال شده است
close_chat
یک گفتگو بسته شد
transfer_chat
یک گفتگو به اپراتور دیگری انتقال یافت
rating
کاربر به اپراتور در یک گفتگو امتیاز داد
نمونه اطلاعات دریافتی
{
"event": "new_message",
"data": {
"chat_id": "61225d8fc0925903200fbc74",
"user_id": "61225d87c0925903200fbc73b0423a29b1330017ea8498167e9a7c024d05c3c8",
"sender": {
"from": "operator",
"name": "ali",
"id": "61031e563060c5ffe08f2525"
},
"date": "2021-09-05 21:38:03",
"content": "How can I help you?",
"type": "text",
"message_id": "5d225d8fc0925903200fb5e1",
"current_owner": ["61031e563060c5ffe08f2525"]
}
}
{
"event": "close_chat",
"data": {
"chat_id": "61225d8fc0925903200fbc74",
"user_id": "61225d87c0925903200fbc73b0423a29b1330017ea8498167e9a7c024d05c3c8",
"date": "2021-09-05 21:38:03",
"action_by": "61225d8fc0925903200fba32"
}
}
{
"event": "transfer_chat",
"data": {
"chat_id": "61225d8fc0925903200fbc74",
"user_id": "61225d87c0925903200fbc73b0423a29b1330017ea8498167e9a7c024d05c3c8",
"date": "2021-09-05 21:38:03",
"action_by": "61225d8fc0925903200fba32",
"to_operator": "5d225d8fc0925903200fb5e1"
}
}
{
"event": "rating",
"data": {
"chat_id": "61225d8fc0925903200fbc74",
"user_id": "61225d87c0925903200fbc73b0423a29b1330017ea8498167e9a7c024d05c3c8",
"date": "2021-09-05 21:38:03",
"rate": "3",
"to_operator": "5d225d8fc0925903200fb5e1"
}
}
خطاها
با ارسال هر درخواست به API گفتینو، وضعیت اجرای متد مورد نظر، در پاسخ مربوطه قابل دسترسی خواهد بود. در صورت بروز خطا، یک کد خطا برای عیب یابی نیز دریافت می شود.
1 :
پارامتر goftino-key ارسالی نامعتبر است
2 :
پارامتر های مورد نیاز متد مربوطه نامعتبر است
3 :
امکان اجرای درخواست با توجه به عدم دسترسی وجود ندارد
4 :
خطای داخلی در انجام درخواست رخ داده است، لطفا مجدد اقدام کنید
5 :
متد مورد نظر شما نامعتبر است
نمونه پاسخ ناموفق200 OK
{
"status": "error"
"code": "4"
}