Ruby SDK for api.ai
Ruby

README.md

The API.AI ruby gem

Gem Version

A Ruby SDK to the https://api.ai natural language processing service.

Installation

gem install api-ai-ruby

Basic Usage

Just pass correct credentials to ApiAiRuby::Client constructor

client = ApiAiRuby::Client.new(
    :client_access_token => 'YOUR_CLIENT_ACCESS_TOKEN'
)

After that you can send text requests to the https://api.ai with command

response = client.text_request 'hello!'

Or try to invocate intent via defined 'event':

response_zero = client.event_request 'MY_CUSTOM_EVENT_NAME';
response_one = client.event_request 'MY_EVENT_WITH_DATA_TO_STORE', {:param1 => 'value'}
response_two = client.event_request 'MY_EVENT_WITH_DATA_TO_STORE', {:some_param => 'some_value'}, :resetContexts => true

voice_request and text_request methods returns symbolized https://api.ai response. Structure of response can be found at https://docs.api.ai/docs/query#response.

Advanced usage

During client instantiating you can additionally set parameters like api url, request language and version (more info at https://docs.api.ai/docs/versioning, https://docs.api.ai/docs/languages)

ApiAiRuby::Client.new(
    client_access_token: 'YOUR_ACCESS_TOKEN',
    api_lang: 'FR',
    api_base_url: 'http://example.com/v1/',
    api_version: 'YYYYMMDD',
    api_session_id: 'some_uuid_or_whatever'
)

And you also can send additional data to server during request, use second parameter of text_request and voice_request methods to do that

    response = client.text_request 'Hello', :contexts => ['firstContext'], :resetContexts => true
    response = client.voice_request file, :timezone => 'America/New_York'

More information about possible parameters can be found at https://docs.api.ai/docs/query page

User Entities

Another possibility is to send and retrieve custom entities to the server.

You can do it along with query request

client.text_request 'call Mozart', entities: [
    {
        name: 'contacts',
        entries: [
            ApiAiRuby::Entry.new('Mozart', %w(Mozart Wolfgang)),
            ApiAiRuby::Entry.new('Salieri', %w(Salieri Antonio))
        ]
    }
]

# the same without ApiAiRuby::Entry wrapper

client.text_request 'call Mozart', entities: [
    {
        name: 'contacts',
        entries: [
            {value: 'Mozart', synonyms: %w(Mozart Wolfgang))},
            {value: 'Salieri', synonyms: %w(Salieri Antonio))},
        ]
    }
]

Or with separate user_entities_request object with full CRUD support:

# preparations
entries_composers = [
    ApiAiRuby::Entry.new('Mozart', %w(Mozart Wolfgang)),
    ApiAiRuby::Entry.new('Salieri', %w(Salieri Antonio))
]

entries_unknown = [
    ApiAiRuby::Entry.new('John Doe', %w(John Unknown)),
    ApiAiRuby::Entry.new('Jane Doe', %w(Jane))
]

entity_contacts = ApiAiRuby::Entity.new('contacts', [entries_composers])

# let's go
uer = client.user_entities_request
uer.create(contacts) # or uer.create([entity1, entity2...])

client.text_request 'call Mozart' # will work

uer.update('contacts', entries_unknown)

client.text_request 'call Mozart' # will NOT work
client.text_request 'call John' # will work

uer.retrieve('contacts') # will return current state of user entity
uer.delete('contacts') # will remove user entities for given session    

Timeouts

ApiAiRuby::Client uses the http gem under the hood. You can use timeout_options on the client to set these.

ApiAiRuby::Client.new(
    client_access_token: 'YOUR_ACCESS_TOKEN',
    api_lang: 'FR',
    api_base_url: 'http://example.com/v1/',
    api_version: 'YYYYMMDD',
    api_session_id: 'some_uuid_or_whatever',
    timeout_options: [:global, { write: 1, connect: 1, read: 1 }]
)

Please see the httprb wiki on timeouts for more information.

Error handling

ApiAiRuby::Client currently able to raise two kind of errors: ApiAiRuby::ClientError (due to configuration mismatch) and ApiAiRuby::RequestError in case of something goes wrong during request. For both kind of errors you can get error.message (as usual) and ApiAiRuby::RequestError can additionally give you code of server error (you can get it with error.code)

Changelog

  • 1.2.3 - events support
  • 1.2.2 - added configurable timeouts for requests (thanks bramski)
  • 1.2.1 - fixed UTF-8 in text-requests
  • 1.2.0 - added configurable session_id and full userEntities support
  • 1.1.4 - removed unused dependency and updated default API version
  • 1.1.3 - fixed non-correctly serialized parameters in new contexts during query send process
  • 1.1.2 - fixed compatibility with ruby version less then 2.1.6