چگونه از وب‌هوک‌ها استفاده کنیم؟

وب‌هوک‌ها، HTTP callback هایی هستند که برای هر حساب تنظیم می‌شوند. اینها زمانی که اقداماتی مانند ایجاد یک پیام در گپیفای رخ می‌دهد، فعال می‌شوند. چندین وب‌هوک می‌توان برای یک حساب ایجاد کرد.

چگونه یک وب‌هوک اضافه کنیم؟

مرحله ۱: به تنظیمات -> برنامه های تلفیق شده -> وب‌هوک‌ها بروید. روی دکمه "تنظیمات" کلیک کنید.

مرحله ۲: روی دکمه "اضافه کردن وب‌هوک جدید" کلیک کنید. یک پنجره باز می‌شود. در اینجا، URL که درخواست POST باید به آن ارسال شود را وارد کنید. سپس، باید رویدادهایی که می‌خواهید مشترک شوید را انتخاب کنید. این گزینه به شما اجازه می‌دهد فقط به رویدادهای مرتبط در گپیفای گوش دهید.

گپیفای یک درخواست POST با payload زیر به URLهای تنظیم شده برای به‌روزرسانی‌های مختلف در حساب شما ارسال می‌کند.

یک نمونه payload وب‌هوک

{

  "event": "message_created", // The name of the event
  "id": "1", // Message ID
  "content": "Hi", // Content of the message
  "created_at": "2020-03-03 13:05:57 UTC", // Time at which the message was sent
  "message_type": "incoming", // This will have a type incoming, outgoing or template. The user from the widget sends incoming messages, and the agent sends outgoing messages to the user.
  "content_type": "enum", // This is an enum, it can be input_select, cards, form or text. The message_type will be template if content_type is one og these. Default value is text
  "content_attributes": {} // This will an object, different values are defined below
  "source_id": "", // This would the external id if the inbox is a Twitter or Facebook integration.
  "sender": { // This would provide the details of the agent who sent this message
    "id": "1",
    "name": "Agent",
    "email": "agent@example.com"
  },
  "contact": { // This would provide the details of the user who sent this message
    "id": "1",
    "name": "contact-name"
  },
  "conversation": { // This would provide the details of the conversation
    "display_id": "1", // This is the ID of the conversation which you can see in the dashboard.
    "additional_attributes": {
      "browser": {
        "device_name": "Macbook",
        "browser_name": "Chrome",
        "platform_name": "Macintosh",
        "browser_version": "80.0.3987.122",
        "platform_version": "10.15.2"
      },
      "referer": "<http://www.gapify.com>",
      "initiated_at": "Tue Mar 03 2020 18:37:38 GMT-0700 (Mountain Standard Time)"
    }
  },
  "account": { // This would provide the details of the account
    "id": "1",
    "name": "Gapify",
  }
}

رویدادهای وب‌هوک پشتیبانی شده در گپیفای

گپیفای رویدادهای مختلف را به نقاط پایانی وب‌هوک پیکربندی شده منتشر می‌کند.

هر رویداد ساختار بار مفقود خود را بر اساس نوع مدلی که بر آن عمل می‌کنند دارد. بخش زیر ویژگی‌های اصلی آبجکت های اصلی که ما در گپیفای استفاده می‌کنیم را توضیح می‌دهد.

آبجکت ها

یک بارگیری رویداد ممکن است حاوی هر یک از آبجکت های زیر باشد. انواع مختلف آبجکت پشتیبانی شده توسط گپیفای به شرح زیر است:

حساب

{
  "id": "integer",
  "name": "string"
}

صندوق ورودی

{
"id": "integer",
"name": "string"
}

تماس

{
  "id": "integer",
  "name": "string",
  "avatar": "string",
  "type": "contact",
  "account": {
    // <...Account Object>
  }
}

کاربر

{
  "id": "integer",
  "name": "string",
  "email": "string",
  "type": "user"
}

گفتگو

{
  "additional_attributes": {
    "browser": {
      "device_name": "string",
      "browser_name": "string",
      "platform_name": "string",
      "browser_version": "string",
      "platform_version": "string"
    },
    "referer": "string",
    "initiated_at": {
      "timestamp": "iso-datetime"
    }
  },
  "can_reply": "boolean",
  "channel": "string",
  "id": "integer",
  "inbox_id": "integer",
  "contact_inbox": {
    "id": "integer",
    "contact_id": "integer",
    "inbox_id": "integer",
    "source_id": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "hmac_verified": "boolean"
  },
  "messages": ["Array of message objects"],
  "meta": {
    "sender": {
      // Contact Object
    },
    "assignee": {
      // User Object
    }
  },
  "status": "string",
  "unread_count": "integer",
  "agent_last_seen_at": "unix-timestamp",
  "contact_last_seen_at": "unix-timestamp",
  "timestamp": "unix-timestamp",
  "account_id": "integer"
}

پیام

{
  "id": "integer",
  "content": "string",
  "message_type": "integer",
  "created_at": "unix-timestamp",
  "private": "boolean",
  "source_id": "string / null",
  "content_type": "string",
  "content_attributes": "object",
  "sender": {
    "type": "string - contact/user"
    // User or Contact Object
  },
  "account": {
    // Account Object
  },
  "conversation": {
    // Conversation Object
  },
  "inbox": {
    // Inbox Object
  }
}

یک نمونه از داده‌های وب‌هوک

{
  "event": "event_name"
  // Attributes related to the event
}

رویدادهای وب‌هوک

گپیفای از رویدادهای وب‌هوک زیر پشتیبانی می‌کند. شما می‌توانید در حالی که یک وب‌هوک را در داشبورد پیکربندی می‌کنید یا از طریق API استفاده می‌کنید، به آن‌ها مشترک شوید.

گفتگو ایجاد شد

این رویداد زمانی فعال می‌شود که یک گفتگو جدید در حساب ایجاد می‌شود. بارگیری برای این رویداد به شرح زیر است.

{
  "event": "conversation_created"
  // <...Conversation Attributes>
}

گفتگو به‌روزرسانی شد

این رویداد زمانی فعال می‌شود که تغییری در هر یک از ویژگی‌های گفتگو رخ دهد.

{
  "event": "conversation_updated",
  "changed_attributes": [
    {
      "<attribute_name>": {
        "current_value": "",
        "previous_value": ""
      }
    }
  ]
  // <...Conversation Attributes>
}

تغییر وضعیت گفتگو

این رویداد زمانی فعال می‌شود که وضعیت گفتگو تغییر کند.

توجه: اگر از واسط‌های بات ایجنت به جای وب‌هوک‌ها استفاده می‌کنید، این رویداد هنوز پشتیبانی نمی‌شود.

{
  "event": "conversation_status_changed"
  // <...Conversation Attributes>
}

پیام ایجاد شد

این رویداد زمانی فعال می‌شود که یک پیام در یک گفتگو ایجاد می‌شود. بارگیری برای این رویداد به شرح زیر است.

{
  "event": "message_created"
  // <...Message Attributes>
}

پیام به‌روزرسانی شد

این رویداد زمانی فعال می‌شود که یک پیام در یک گفتگو به‌روزرسانی شود. بارگیری برای این رویداد به شرح زیر است.

{
  "event": "message_updated"
  // <...Message Attributes>
}

ویجت وب فعال شد

این رویداد زمانی فعال می‌شود که کاربر نهایی ویجت گفتگو زنده را باز می‌کند.

{
  "id": ,
  "contact": {
    // <...Contact Object>
  },
  "inbox": {
    // <...Inbox Object>
  },
  "account": {
    // <...Account Object>
  },
  "current_conversation": {
    // <...Conversation Object>
  },
  "source_id": "string",
  "event": "webwidget_triggered",
  "event_info": {
    "initiated_at": {
      "timestamp": "date-string"
    },
    "referer": "string",
    "widget_language": "string",
    "browser_language": "string",
    "browser": {
      "browser_name": "string",
      "browser_version": "string",
      "device_name": "string",
      "platform_name": "string",
      "platform_version": "string"
    }
  }
}