اپراتورها
راهنمای استفاده
گفتینو این امکان را به شما می دهد که توسط API ارایه شده، به بخش هایی از سامانه خود دسترسی و از آنها برای مدیریت گفتگوها و کاربران استفاده نمایید. (به مرور امکانات موجود در API توسعه خواهد یافت)
احراز هویت :
برای ارسال و دریافت اطلاعات در API گفتینو در شناسایی و اعتبار سنجی حساب کاربری، از پارامتر goftino-key استفاده می شود. در تنظیمات سامانه ، بخش api را برای دریافت این پارامتر بررسی کنید.
ارسال Header :
برای ایجاد هر نوع درخواست در API گفتینو ، از نمونه Header ارایه شده، همراه با مقادیر مورد نیاز هر متد ، استفاده نمایید.
محدودیت درخواست :
جهت حفظ پایداری و امنیت سرویس ، تعداد ارسال لحظه ای درخواست ها به API گفتینو محدودیت دارد و طبق سیاست استفاده منصفانه ارایه خواهد شد.
Headers

Content-Type: application/json
goftino-key: YOUR-API-KEY

send_message
POST https://api.goftino.com/v1/send_message
از این متد برای ارسال پیام متنی از اپراتور به کاربر استفاده می شود.
داده های ارسالی :
chat_id
(string)اجباری
id گفتگوی مورد نظر
operator_id
(string)اجباری
id اپراتور ارسال کننده پیام
message
(string)اجباری
متن پیام ارسالی
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --location --request POST 'https://api.goftino.com/v1/send_message' \
--header 'Content-Type: application/json' \
--header 'goftino-key: YOUR-API-KEY' \
--data-raw '{"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"
}
close_chat
POST https://api.goftino.com/v1/close_chat
از این متد برای بستن گفتگو استفاده می شود.
داده های ارسالی :
chat_id
(string)اجباری
id گفتگوی مورد نظر
operator_id
(string)اجباری
id اپراتور مورد نظر
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --location --request POST 'https://api.goftino.com/v1/close_chat' \
--header 'Content-Type: application/json' \
--header 'goftino-key: YOUR-API-KEY' \
--data-raw '{"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 --location --request POST 'https://api.goftino.com/v1/transfer_chat' \
--header 'Content-Type: application/json' \
--header 'goftino-key: YOUR-API-KEY' \
--data-raw '{"chat_id":"61031e563060c5ffe08f8777","from_operator":"609bee1fb5f9aa2640e9fd57","to_operator":"619bee1fb579a82640e9e118"}'
Body
{
    "chat_id": "61031e563060c5ffe08f8777",
    "from_operator": "609bee1fb5f9aa2640e9fd57"
    "to_operator": "619bee1fb579a82640e9e118"
}                    
نمونه پاسخ موفق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 --location --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"
            }
        ]
    }
}
chat_data
GET https://api.goftino.com/v1/chat_data
از این متد برای دریافت اطلاعات و پیام های یک گفتگو استفاده می شود.
داده های ارسالی : (Query string)
chat_id
(string)اجباری
id گفتگوی مورد نظر
داده های خروجی :
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]) - لیست پیام ها
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) - محتوای فیلد
نمونه درخواست
curl --location --request GET 'https://api.goftino.com/v1/chat_data?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",
        "current_owner": ["607013e5fc6a0b37b4007c6d"],
        "all_operators": [ ],
        "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"
            }
        ]
    }
}
chats
GET https://api.goftino.com/v1/chats
از این متد برای دریافت لیست کل گفتگوها استفاده می شود.
داده های ارسالی : (Query string)
limit
(string)
تعداد گفتگو در لیست خروجی (حداکثر 50)
page
(string)
شماره صفحه لیست گفتگوها
داده های خروجی :
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 --location --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
    }
}
set_user_data
POST https://api.goftino.com/v1/set_user_data
از این متد برای ارسال اطلاعات کاربر به گفتینو استفاده می شود.
داده های ارسالی :
user_id
(string)اجباری
id کاربر مورد نظر
name
(string)اختیاری
نام کاربر
phone
(string)اختیاری
شماره تلفن کاربر
email
(string)اختیاری
ایمیل کاربر
avatar
(string)اختیاری
تصویر کاربر
description
(string)اختیاری
توضیحات جانبی کاربر
tags
(array)اختیاری
برچسب
داده های خروجی :
status
(string) - وضعیت موفق یا ناموفق بودن درخواست ارسالی
code
(string) - در صورت عدم موفقیت، کد خطا دریافت می شود
نمونه درخواست
curl --location --request POST 'https://api.goftino.com/v1/set_user_data' \
--header 'Content-Type: application/json' \
--header 'goftino-key: YOUR-API-KEY' \
--data-raw '{"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"
}
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 --location --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"
    }
}
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 --location --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 شما، ارسال اطلاعات بطور موقت غیرفعال خواهد شد.
رویداد های دریافتی :
new_message
یک پیام در سامانه از سوی کاربر یا اپراتور ارسال شده است
نمونه اطلاعات دریافتی
{
    "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"
    }
}
خطاها
با ارسال هر درخواست به API گفتینو، وضعیت اجرای متد مورد نظر، در پاسخ مربوطه قابل دسترسی خواهد بود. در صورت بروز خطا، یک کد خطا برای عیب یابی نیز دریافت می شود.
1 : پارامتر goftino-key ارسالی نامعتبر است
2 : پارامتر های مورد نیاز متد مربوطه نامعتبر است
3 : امکان اجرای درخواست با توجه به عدم دسترسی وجود ندارد
4 : خطای داخلی در انجام درخواست رخ داده است، لطفا مجدد اقدام کنید
5 : متد مورد نظر شما نامعتبر است
نمونه پاسخ ناموفق200 OK
{
    "status": "error"
    "code": "4"
}