Creating Chat Session
The chat session is the most important concept of a chat process.
It leads through the states of the chat process, enabling to perform the next step needed, and disabling actions that should not be done at the moment. It builds up pre, post and unavailable chat forms, and submits the answers of the user. It does not handle the chatting directly. Instead, it instantiates the chat object for that.
To create a chat session use the following code:
id <BCCancelable> cancelable = [account createChatSessionWithDelegate:<create chat session delegate> language:<language string> visitorId:<customer Id> skipPreChat:YES/NO externalParams:<external params>];The language of the chat can be set explicitly here. The language parameter must be an ISO 639-1 language code optionally followed by a dash then an ISO 3166-1 country code (en-US). If a language code is passed that is not recognized or supported en-US strings will be returned instead. If this parameter is not set, the application language will be tried to use.
The list of supported languages can be set per application. The current system supports the following languages:
| af-ZA - Afrikaans | de-DE - German | pl-PL - Polish |
| ar - Arabic | el-GR - Greek | pt-PT - Portuguese |
| bn-BD - Bengali | he-IL - Hebrew | pt-BR - Portuguese (Brazilian) |
| bg-BG - Bulgarian | hi-IN - Hindi | pa-IN - Punjabi |
| zh-CN - Chinese (Simplified) | hu-HU - Hungarian | ro-RO - Romanian |
| zh-TW - Chinese (Traditional) | is-IS - Icelandic | ru-RU - Russian |
| hr-HR - Croatian | id-ID - Indonesian | sk-SK - Slovak |
| cs-CZ - Czech | ga-IE - Irish | es-ES - Spanish |
| da-DK - Danish | it-IT - Italian | sv-SE - Swedish |
| nl-NL - Dutch | ja-JP - Japanese | th-TH - Thai |
| en-GB - English (United Kingdom) | ko-KR - Korean | tr-TR - Turkish |
| fi-FI - Finnish | ms-MY - Malay | uk-UA - Ukranian |
| fr-FR - French | nb-NO - Norwegian (Bokmal) | vi-VN - Vietnamese |
| fr-CA - French (Canadian) | nn-NO - Norwegian (Nynorsk) |
The visitorId is optional. If not set, a random one is assigned to the user at every chat creation. The assigned visitorId can be obtained from chatSession when created. It is for tracking the customer and for the implementation of customer blocking.
If pre-chat is defined for the chat, the developer can force to skip it by skipPreChat parameter. Pre defined values of pre and post chat form fields can be set through extraParams dictionary. The pre-defined set of extra parameter keys are defined in BCAccount.h
| Variable Reference in BCAccount.h | Name as External Parameter | Description |
|---|---|---|
| BCFormFieldLanguage | language | Language string |
| BCFormFieldDepartment | department | The ID of the department of the chat |
| BCFormFieldFirstName | first_name | The name of the customer |
| BCFormFieldName | name | The name of the customer (synonymous with first_name) |
| BCFormFieldLastName | last_name | The last name of the customer |
| BCFormFieldPhone | phone | The phone number of the customer |
| BCFormFieldEmail | The email of the customer | |
| BCFormFieldInitialQuestion | initial_question | The initial question for the chat (which will show as the first chat message in the chat from the customer) |
| BCFormFieldReference | reference | The customer reference value that appears in the client |
| BCFormFieldInformation | information | The customer info value that appears in the client |
| BCFormFieldOverall | overall | Survey overall response value. The value needs to given in NSNumber |
| BCFormFieldKnowledge | knowledge | Survey knowledge response value. The value needs to given in NSNumber |
| BCFormFieldResponsiveness | responsiveness | Survey responsiveness response value. The value needs to given in NSNumber |
| BCFormFieldProfessionalism | professionalism | Survey professionalism response value. The value needs to given in NSNumber |
| BCFormFieldComments | comments | Survey comments response value |
| BCFormFieldCustomUrl | CustomUrl | Custom redirect URL |
- BCFormFieldComments(name): Macro for naming custom parameters
The delegate of the request receives the result of creating a chat.
- (void)bcAccount:(BCAccount *)account didCreateChatWithoutPreChat:(id<BCChatSession>)chatSession andDidStartChat:(id<BCChat>)chat {
// The chat session was created. There is no defined pre-chat for the customer.
// The chat instance is also created and started, delegates can be added.
}
- (void)bcAccount:(BCAccount *)account didCreateChat:(id<BCChatSession>)chatSession withPreChat:(BCForm *)preChat {
// The chat session was created with a pre-chat form that needs to be filled.
}
- (void)bcAccount:(BCAccount *)account didCreateChat:(id<BCChatSession>)chatSession unavailableWithReason:(BCUnavailableReason)reason unavailableForm:(BCForm *)unavailableForm unavailableMessage:(NSString *)message {
// The chat is unavailable for the reason set in reason variable defined in [Chat availability checking].
// The unavailable form set for this case is also given in unavailableForm. If it is empty, the chat session ended.
// Message can be presented that is a textural description for the current unavailable reason.
}
- (void)bcAccount:(BCAccount *)account didFailToCreateWithError:(NSError *)error {
//Failed to create chat session.
//Check error.code to values from BCErrorCodes.h to find out the cause of the error.
}In the following sections there are many properties that hold string keys for localization. The actual localization or branding dictionary is available through chatSession.branding property, after the session is created, or the language is changed.