Recast.AI official SDK in Swift.
This pod is a Swift interface to the Recast.AI API. It allows you to make requests to your bots.
- iOS 8.0+
- Xcode 7.2+
RecastAI is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod "RecastAI"
To run the example project, clone the repo, and run pod install
from the Example directory first.
This class handles everything. Create a RecastAIClient object and init it with your token and a class that implements the HandlerRecastRequestProtocol
Protocol. The RecastAIClient can also be instanciated with a language (optional).
import RecastAI
class ViewController: UIViewController, HandlerRecastRequestProtocol
{
var bot : RecastAIClient?
override func viewDidLoad()
{
super.viewDidLoad()
// Do any additional setup after loading the view, typically from a nib.
//Initialise bot with token & handlerRecastProtocol with and without a language as a parameter
self.bot = RecastAIClient(token: YOUR_BOT_TOKEN, handlerRecastRequestProtocol: <#T##HandlerRecastRequestProtocol#>)
self.bot = RecastAIClient(token: YOUR_BOT_TOKEN, handlerRecastRequestProtocol: <#T##HandlerRecastRequestProtocol#>, language: <#T##String?#>)
}
}
- Text Request
The textRequest
method allows you to make a request to the Recast.AI API. The textRequest
method is to make a Text request and takes a text as a String
as parameter and a language as a String
as an optional parameter. If no language is provided in the request, the language of the text is detected and is used for processing if your bot has expressions for it, else your bot's primary language is used for processing.
/**
Make text request to Recast.AI API
*/
@IBAction func makeRequest()
{
//Call makeRequest with string parameter to make a text request with and without language as a parameter
self.bot?.textRequest(<#T##request: String##String#>)
self.bot?.textRequest(<#T##request: String##String#>, lang: <#T##String?#>)
}
- Stream Request
In order to make a Voice Request you need to implement two methods startStreamRequest
& stopStreamRequest
. startStreamRequest
will start recording your voice and stopStreamRequest
will stop recording your voice and send the request to the Recast.AI API.
//Bool to check if currently recording voice
var recording : Bool = true
/**
Make Voice request to Recast.AI API
*/
@IBAction func makeVoiceRequest()
{
if (self.recording)
{
self.recording = !self.recording
//Call startStreamRequest to start recording your voice
self.bot!.startStreamRequest()
}
else
{
self.recording = !self.recording
//Call stopStreamRequest to stop recording your voice and launch the request to the Recast.AI API
self.bot!.stopStreamRequest()
}
}
- handlerRecastRequestProtocol
In order to comply with the handlerRecastRequestProtocol you need to implement recastRequestDone
& recastRequestError
.
recastRequestDone
is called when the request was successful with the Response in parameterrecastRequestError
is called when the request failed with the error in parameter
public protocol HandlerRecastRequestProtocol : class
{
//If success
func recastRequestDone(response : Response)
//If failure
func recastRequestError(error : NSError)
}
Implement those metods in your ViewController.
/**
Method called when the request was successful
- parameter response: the response returned from the Recast API
- returns: void
*/
func recastRequestDone(response : Response)
{
print(response.source)
}
/**
Method called when the request failed
- parameter error: error returned from the Recast API
- returns: void
*/
func recastRequestError(error : NSError)
{
print("Delegate Error : \(error)")
}
Once you made the request to the API, you receice a response. Response contains an array of intents sorted by probability and an array of the sentences you sent through the textRequest
method.
public class Response
{
public var source : String?
public var intents : [String]?
public var sentences : [Sentence]?
public var language : String?
public var version : String?
public var timestamp : String?
public var status : Int?
public var raw : [String : AnyObject]?
}
A Sentence contains the following attributes and the object Entities
public class Sentence
{
public var source : String?
public var type : String?
public var polarity : String?
public var action : String?
public var agent : String?
public var entities : Entities?
}
All the entities implement the CustomStringConvertible
protocol. See Apple documentation CustomStringConvertible for more information.
This is the list of the current entities we detect.
public class Entities
{
public var ages : [Age]?
public var cardinals : [Cardinal]?
public var colors : [Color]?
public var datetimes : [Datetime]?
public var distances : [Distance]?
public var durations : [Duration]?
public var emails : [Email]?
public var ips : [IP]?
public var jobs : [Job]?
public var languages : [Language]?
public var locations : [Location]?
public var masses : [Mass]?
public var miscs : [Misc]?
public var moneys : [Money]?
public var nationalities : [Nationality]?
public var numbers : [Number]?
public var ordinals : [Ordinal]?
public var organizations : [Organization]?
public var percents : [Percent]?
public var persons : [Person]?
public var pronouns : [Pronoun]?
public var sets : [Set]?
public var sorts : [Sort]?
public var speeds : [Speed]?
public var temperatures : [Temperature]?
public var urls : [Url]?
public var volumes : [Volume]?
public var customs : [Custom]?
}
You can print a description of the entity using the description method :
public var description: String
{
return "Custom(value : \(value), raw : \(raw))"
}
- Accessing Entities
You can access ages
entities from the first sentence this way :
response.sentences![0].entities?.ages
- Accessing Custom Entities
If you want to get custom entities you can do it this way :
print(response.sentences![0].entities?.custom)
Output :
Optional(["movie": [Custom(value : star wars 8, raw : Star Wars 8)]])
If you want to access the array of a specific custom entity you can do it with its key:
print(response.sentences![0].entities?.custom!["movie"]
Output :
Optional([Custom(value : star wars 8, raw : Star Wars 8)])
We will call recastRequestError
with NSError as parameter.
For more information about Recast Errors check out our man#error
You can view the whole API reference at man.recast.ai
PE Lieb, pierre-edouard.lieb@recast.ai, @pedward_lieb
You can follow us on Twitter at @recastai for updates and releases.
RecastAI is available under the MIT license.
Copyright (c) 2016 RecastAI
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.