Skip to content

Latest commit

 

History

History
532 lines (386 loc) · 13.5 KB

apis.md

File metadata and controls

532 lines (386 loc) · 13.5 KB

API References

Index

initialize

Initializing Zendesk SDK.

You should call this function first before using other features.

  • Parameters
    Name Type Required
    config ZendeskInitializeConfig Yes
  • Return Value
    Type
    Promise<void> 
/* interfaces */

interface ZendeskInitializeConfig {
  channelKey: string;
  skipOpenMessaging?: boolean; // iOS Only
}

function initialize(config: ZendeskInitializeConfig): Promise<void>
initialize({ channelKey: 'YOUR_ZENDESK_CHANNEL_KEY' });
  • channelKey: Zendesk channel key
  • skipOpenMessaging: skip open messaging view after initialize successfully (default: false, iOS only)
    • application started by Zendesk push notification, showing messaging view for users.

reset

Invalidates the current instance of Zendesk. After calling this method you will have to call initialize again if you would like to use Zendesk.

  • Return Value
    Type
    void 
/* interfaces */

function reset(): void
reset();

login

To authenticate a user call the login with your own JWT.

  • Parameters
    Name Type Required
    token string Yes
  • Return Value
    Type
    Promise<ZendeskUser> 
/* interfaces */

interface ZendeskUser {
  id: string;
  externalId: string;
}

function login(token: string): Promise<ZendeskUser>
const user = await login('eyJhb...Your own JWT...ssw5c');

logout

To unauthenticate a user call the logout.

  • Return Value
    Type
    Promise<void> 
/* interfaces */

function logout(): Promise<void>
logout();

openMessagingView

Show the native based conversation screen.

  • Return Value
    Type
    Promise<void> 
/* interfaces */

function openMessagingView(): Promise<void>
openMessagingView();

closeMessagingView

Important

iOS only (no-op for other platform, always return empty promise)

Close the messaging view if it is open.

  • Return Value
    Type
    Promise<void> 
/* interfaces */

function closeMessagingView(): Promise<void>
closeMessagingView();

sendPageViewEvent

Send session-based page view event. event must have pageTitle and url.

Sent events can be seen in agent workspace by support agents using Zendesk.

  • Parameters
    Name Type Required
    event ZendeskPageViewEvent Yes
  • Return Value
    Type
    Promise<void> 
/* interfaces */

interface ZendeskPageViewEvent {
  pageTitle: string;
  url: string;
}

function sendPageViewEvent(event: ZendeskPageViewEvent): Promise<void>
sendPageViewEvent({
  pageTitle: 'Home',
  url: 'RootStack/HomeScreen', // eg. react-navigation's current path string
});

setConversationFields

Allows values for conversation fields to be set in the SDK to add contextual data about the conversation.

Note

Conversation fields are not immediately associated with a conversation when the API is called. Calling the API will store the conversation fields, but those fields will only be applied to a conversation when end users either start a new conversation or send a new message in an existing conversation.

Note

An event for handling failed validation checks on conversation fields set using the setConversationFields API will be added in an upcoming release of the Zendesk SDK.

  • Parameters
    Name Type Required
    fields `Record<string, string number
  • Return Value
    Type
    void 
/* interfaces */

function setConversationFields(fields: Record<string, string | number | boolean>): void
setConversationFields({ '4422761977114': 'FA2590' });

clearConversationFields

You can clear conversation fields from the SDK storage when the client side context changes. To do this, use the clearConversationFields API. This removes all stored conversation fields from the SDK storage.

Note

This API does not affect conversation fields already applied to the conversation.

  • Return Value
    Type
    void 
/* interfaces */

function clearConversationFields(): void
clearConversationFields();

setConversationTags

Allows custom conversation tags to be set in the SDK to add contextual data about the conversation.

To use conversation tags, refer to Using Messaging Metadata with the Zendesk Web Widgets and SDKs.

Note

Conversation tags are not immediately associated with a conversation when the API is called. It will only be applied to a conversation when end users either start a new conversation or send a new message in an existing conversation.

  • Parameters
    Name Type Required
    tags string[] Yes
  • Return Value
    Type
    void 
/* interfaces */

function setConversationTags(tags: string[]): void
setConversationTags(['promo_code', 'discount']);

clearConversationTags

Allows you to clear conversation tags from SDK storage when the client side context changes. To do this, use the clearConversationTags API. This removes all stored conversation tags from the SDK storage.

Note

This API does not affect conversation tags already applied to the conversation.

  • Return Value
    Type
    void 
/* interfaces */

function clearConversationTags(): void
clearConversationTags();

updatePushNotificationToken

Important

Android only (no-op for other platform, always return empty promise)

To enable a device to receive push notifications, you must notify the SDK when a new FCM token has been created.

  • Parameters
    Name Type Required
    token string Yes
  • Return Value
    Type
    void 
/* interfaces */

function updatePushNotificationToken(token: string): void
updatePushNotificationToken('...FCM Token...');

getUnreadMessageCount

Get current total number of unread messages.

  • Return Value
    Type
    Promise<number> 
/* interfaces */

function getUnreadMessageCount(): Promise<number>
const unreadCount = await getUnreadMessageCount();

handleNotification

Handle remote message that received from FCM(Firebase Cloud Messaging) and show notifications.

If remote message isn't Zendesk message, it does nothing.

Important

Android only (always returns UNKNOWN for others)

This method for integrate with @react-native-firebase/messaging.

For more details, read the Push Notifications guide.

  • Parameters
    Name Type Required
    remoteMessage object Yes
  • Return Value
    Type
    Promise<ZendeskNotificationResponsibility>
    • MESSAGING_SHOULD_DISPLAY: remoteMessage is handled by Zendesk SDK. it will be appeared as notification
    • MESSAGING_SHOULD_NOT_DISPLAY: remoteMessage is handled by Zendesk SDK. but, it's not appear as notification (eg. bot response)
    • NOT_FROM_MESSAGING: remoteMessage is not handled by Zendesk SDK
    • UNKNOWN: If platform is iOS always return this value and otherwise used by fallback value.
/* interfaces */
type ZendeskNotificationResponsibility =
  | 'MESSAGING_SHOULD_DISPLAY'
  | 'MESSAGING_SHOULD_NOT_DISPLAY'
  | 'NOT_FROM_MESSAGING'
  | 'UNKNOWN';

function handleNotification(remoteMessage: Record<string, string>): Promise<ZendeskNotificationResponsibility>
const responsibility = await handleNotification({ ... });

addEventListener

Add a listener for listening emitted events by Zendesk SDK.

  • Parameters
    Name Type Required
    type ZendeskEventType Yes
    listener (event) => void Yes
  • Return Value
    Type
    EmitterSubscription 
/* interfaces */

type ZendeskEventType = 'unreadMessageCountChanged' | 'authenticationFailed';

function addEventListener<EventType extends ZendeskEventType>(type: EventType, listener: (event: ZendeskEventResponse[EventType]) => void): EmitterSubscription
const unreadMessageCountChangedSubscription = addEventListener('unreadMessageCountChanged', (event) => {
  // Event type
  // { unreadCount: number; }
});

const authenticationFailedSubscription = addEventListener('authenticationFailed', (event) => {
  // Event type
  // { reason: string; }
});

removeSubscription

Remove subscribed event listener

  • Parameters
    Name Type Required
    subscription EmitterSubscription Yes
  • Return Value
    • void
/* interfaces */

function removeSubscription(subscription: EmitterSubscription): void
removeSubscription(subscription);

removeAllListeners

Remove all of registered listener by event type.

  • Parameters
    Name Type Required
    type ZendeskEventType Yes
  • Return Value
    • void
/* interfaces */

function removeAllListeners(type: ZendeskEventType): void
removeAllListeners('unreadMessageCountChanged');