The API.AI ruby gem

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!'

And voice requests with file stream

file=File.new'hello.wav'response=client.voice_request(file)

Example answer:

{
:id => "6daf5ab7-276c-43ad-a32d-bf6831918492",
:timestamp => "2015-12-22T08:42:15.785Z",
:result => {
:source => "agent",
:resolvedQuery => "Hello",
:speech => "Hi! How are you?",
:action => "greeting",
:parameters => {},
:contexts => [],
:metadata => {
:intentId => "a5d685ab-1f19-46b0-9478-69f794553668",
:intentName => "hello"
}
},
:status => {
:code => 200,
:errorType => "success"
}
}

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=>trueresponse=client.voice_requestfile,: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(MozartWolfgang)),ApiAiRuby::Entry.new('Salieri',%w(SalieriAntonio))]}]# the same without ApiAiRuby::Entry wrapperclient.text_request'call Mozart',entities: [{name: 'contacts',entries: [{value: 'Mozart',synonyms: %w(MozartWolfgang))},{value: 'Salieri',synonyms: %w(SalieriAntonio))},]}]

Or with separate user_entities_request object with full CRUD support:

# preparationsentries_composers=[ApiAiRuby::Entry.new('Mozart',%w(MozartWolfgang)),ApiAiRuby::Entry.new('Salieri',%w(SalieriAntonio))]entries_unknown=[ApiAiRuby::Entry.new('John Doe',%w(JohnUnknown)),ApiAiRuby::Entry.new('Jane Doe',%w(Jane))]entity_contacts=ApiAiRuby::Entity.new('contacts',[entries_composers])# let's gouer=client.user_entities_requestuer.create(contacts)# or uer.create([entity1, entity2...])client.text_request'call Mozart'# will workuer.update('contacts',entries_unknown)client.text_request'call Mozart'# will NOT workclient.text_request'call John'# will workuer.retrieve('contacts')# will return current state of user entityuer.delete('contacts')# will remove user entities for given session 

#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)

#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.

#Changelog

• 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