Dialog Ruby

A ruby client for the Dialog API.

Examples

• Amazon Alexa (soon)
• Google Actions (soon)
• Facebook Messenger
• Telegram
• Kik (soon)
• Twilio Programmable Chat (soon)
• Twilio SMS

Installation

gem install dialog-api

Or with bundler:

gem 'dialog-api', require: 'dialog-api'

Usage

This library needs to be configured with your API token which is available in your personal account, and a bot ID.

dialog = Dialog.new({
  api_token: ENV['DIALOG_API_TOKEN'],
  bot_id: ENV['DIALOG_BOT_ID'],
  on_error: Proc.new do |status, message, detail|
    p [status, message, detail]
  end
})

Tracking messages

Generic

See docs.dialoganalytics.com/reference/track

payload = {
  message: {
    platform: "messenger",
    provider: "dialog-ruby",
    mtype: "text",
    sent_at: 1482266741.18,
    nlp: {
      intents: [
        {
          name: "rocket.launch",
          confidence: 0.98
        }
      ]
    },
    properties: {
      text: "Launch some space rockets"
    }
  },
  conversation: {
    distinct_id: "da58db1e-da73-4628-9dd6-11a524cc3f80"
  },
  creator: {
    distinct_id: "d5ae3f5f-1645-40c3-a38a-02382cd0ee49",
    type: "interlocutor",
    username: "@elon",
    first_name: "Elon",
    last_name: "Musk",
    email: "elon@spacex.com",
    gender: "male",
    locale: "US",
    phone: "1234567890",
    profile_picture: "http://spacex.com/elon.jpg",
    timezone: -5
  }
}

dialog.track(payload)

Events

Send events to Dialog to keep track of your custom logic. Optionally pass an Interlocutor's distinct id to tie the event to one of your bot's interlocutors. See docs.dialoganalytics.com/reference/event#create

dialog.event('subscribed', 'interlocutor_distinct_id', { custom: 'value' })

Clicks

Record clicks by interlocutors inside a conversation using a trackable link. For every links that needs to be tracked, generate a trackable URL by passing the interlocutor's distinct Id (provided by the platform or provider) and the url to the link method. See docs.dialoganalytics.com/reference/click-tracking

dialog.link('http://example.com', interlocutor_distinct_id)
# => https://api.dialoganalytics.com/v1/b/7928374/clicks/?id=123456&url=http%3A%2F%2Fexample.com

Attach

Modify the current track payload about to be sent to Dialog's API with this helper method.

For example, you can specify a message name:

dialog.attach('welcome')
dialog.attach({ message: { name: 'welcome' }}) // equivalent

This will modify the track payload:

{
  message: {
    name: "welcome",
    ...
  },
  conversation: { ... },
  creator: { ... }
}

Messages

Retrieve a message

See docs.dialoganalytics.com/reference/message#retrieve

dialog.message(conversation_id, message_id)

List all messages

List all messages in a conversation. See docs.dialoganalytics.com/reference/message#list

dialog.messages(conversation_id)

Conversations

Retrieve a conversation

See docs.dialoganalytics.com/reference/conversation#retrieve

dialog.conversation(conversation_id)

List all conversations

See docs.dialoganalytics.com/reference/conversation#list

dialog.conversations

Interlocutors

List all interlocutors

See docs.dialoganalytics.com/reference/interlocutor#list

dialog.interlocutors

Retrieve an interlocutor

See docs.dialoganalytics.com/reference/interlocutor#retrieve

dialog.interlocutor(interlocutor_id)

Update an interlocutor

See docs.dialoganalytics.com/reference/interlocutor#update

dialog.update_interlocutor(interlocutor_id, params)

Creating an interlocutor

To create an interlocutor, use the track endpoint. An interlocutor must initially be created in association with a conversation. See docs.dialoganalytics.com/reference/track

Multiple clients

Different parts of your application may require different types of configurations or even sending to multiple bots. In that case, you can initialize multiple instances of Dialog with different settings:

messenger_dialog = Dialog.new(api_token: ENV['DIALOG_API_TOKEN'], bot_id: 'messenger_bot_id')

kik_dialog = Dialog.new(api_token: ENV['DIALOG_API_TOKEN'], bot_id: 'kik_bot_id')

Documentation

See the API docs.

Development

Run all tests:

bundle exec rspec