-
Notifications
You must be signed in to change notification settings - Fork 5
/
openapi.yaml
10285 lines (9609 loc) · 363 KB
/
openapi.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.1
info:
title: Gladly API
description: >-
# Introducing the Gladly API
At Gladly, we believe that customer service is best when it's a
conversation.
That means more than just helping customers with one-off questions or
issues: it's about making them feel known, valued, and respected for the
individuals they are.
The Gladly API was built to help facilitate those relationships, providing
agents with the rich customer context
they need to deliver seamless experiences that make customers feel like
they're more than just a number in a sea of others.
# Overview
You can integrate easily with Gladly by calling Gladly's [REST
API](https://developer.gladly.com/rest/)
and implementing the [Lookup API](https://developer.gladly.com/rest/) to
provide data from your own services.
Some examples of what you do through Gladly APIs include managing customer
profile data, interacting with a customer's timeline,
providing the latest information about a customer's orders, and more.
## REST API
Clients can access the **REST API** via HTTPS at your organization's Gladly
domain (e.g. `https://{organization}.gladly.com`).
Resources follow REST semantics and utilize industry-standard HTTP verbs,
response codes, and authentication schemes.
In addition, all responses and payloads are in JSON with consistent error
codes and formats.
## Lookup API
The Gladly **Lookup API** allows your organization to provide data services
to power the agent's experience with a complete view of your customers'
information, transactions, and activity. You can provide a web service that
implements the Lookup API and Gladly will call it when that data is needed.
Like the REST API, the Lookup API is specified using REST semantics, and
exchanges JSON requests and responses authenticated and signed with secure
keys.
Gladly will perform lookups when certain activities occur within Gladly,
such as when a customer's profile is loaded.
A detailed overview of Lookup Adaptor architecture, requests, resposnes and
more can be found
[here](https://help.gladly.com/developer/docs/lookup-adapter-introduction).
## Testing
Test the myriad possibilities of the Gladly API in a safe, secure space.
We'll enable the Gladly API in a separate sandbox environment, so you can
experiment freely without impacting your production environment (or vice
versa).
Your sandbox environment is accessible at
`https://{organization}.gladly.qa`, where `organization` is your company
name. For specific API endpoints, see documentation below.
# Getting Started
Think of this section as getting the keys to unlocking your access to the
Gladly APIs.
First, you'll need to set up an account with the necessary API
[permissions](https://developer.gladly.com/rest/).
With these permissions, you can then go on to create the [API
Token(s)](https://developer.gladly.com/rest/) you need to access Gladly's
API [resources](https://developer.gladly.com/rest/).
## Permissions
Gladly Administrators can set API permissions on an agent-by-agent basis.
We'll discuss how this maps to API access in the section on
[authentication](https://developer.gladly.com/rest/) below.
To allow a user to create API tokens and access the API:
1. Log in to your Gladly instance.
2. Open the menu on the top left-hand corner of the page.
3. Navigate to **Settings** > **Users*
4. Search and click the user profile you wish to give access to.
5. You'll see a permission called **API User**. Select it, while making sure
to keep the user's **Agent** role intact.
6. Hit **Save** to give access.
We recommend creating a dedicated user to make API calls, whose account
won't be used for agent and organization management.
This will help you with any future audits of API activity vs. agent
activity.
## Creating API Tokens
You must create an API token to access Gladly API resources (see above
[Permissions](https://developer.gladly.com/rest/)).
If your profile already has access to the **API User** permission, you'll
see a menu item titled **More settings**. Click **More settings**:
Click **API Tokens**, then the **Create Token** button on the upper
right-hand corner of the page:
A token will be generated and named, by default, **New Token** (though
depending on whether you have existing tokens, it may be named New Token 2,
or New Token 3, etc.).
You can rename the token to something more easily referenceable by clicking
the name to edit.
This token will be associated with your agent profile, which we refer to as
the API User in this document.
For security purposes, you'll only see a new token once before you navigate
away from the page.
## Replacing/Rotating API Tokens
Should you lose this token, or wish to rotate your application keys, you can
do the following:
1. Generate a new token.
2. Store the new token in a secure location.
3. Delete the old token.
4. Update your applications/scripts with the new token.
# Authentication
<!-- ReDoc-Inject: <security-definitions> -->
version: '1.0'
x-api-status-urls: false
x-konfig-ignore:
object-with-no-properties: true
potential-incorrect-type: true
servers:
- url: https://organization.gladly.com
tags:
- description: >
## Conversation
A **Conversation** in Gladly contains the timeline of activity for a
customer including communications to and from your organization along with
other internal and external activity.
Conversations API enables you to interact with the customer conversation
timeline.
## Conversation Items
A number of different types of items may appear in a customer's timeline.
Each is described below.
| Item Type | Item Definition | Create | Read | Update
| Delete | Media |
|-------------------------------|----------------|--------|------|--------|--------|--------|
| Chat Message | A message sent/received via the
[Chat](https://help.gladly.com/docs/add-and-configure-chat-entry-points#)
channel | Yes | Yes | No | No | No |
| Conversation Status Change | Conversation status changed (e.g.: from
OPEN to WAITING, or OPEN to CLOSED) | Yes | Yes | Yes | No |
No |
| Custom Channel Message | A Message sent/received via a Custom
Channel integration | No | Yes | No | No | No |
| Customer Activity | Non-routable customer activity added to
customer timeline via API | Yes | Yes | No | Yes | No |
| Email | A message sent/received via the
[Email](https://help.gladly.com/docs/add-and-configure-email-entry-point)
channel | Yes | Yes | No | No | No |
| Facebook Messenger Message | A message sent/received via the
[Facebook
Messenger](https://help.gladly.com/docs/set-up-and-configure-facebook-messenger)
channel | Yes | Yes | No | No | No |
| Instagram Direct | A message sent/received via the
[Instagram](https://help.gladly.com/docs/set-up-and-configure-instagram-messaging)
channel | No | Yes | No | No | No |
| Note | An internal
[Note](https://help.gladly.com/docs/add-a-note-to-a-conversation) on the
Customer conversation | Yes | Yes | No | No | No |
| Phone Call | A [Phone
Call](https://help.gladly.com/docs/add-and-configure-voice-entry-points)
placed/received on Gladly | No | Yes | No | No | Yes |
| SMS Message | A message sent/received via the
[SMS](https://help.gladly.com/docs/add-and-configure-sms-entry-points)
channel | Yes | Yes | No | No | No |
| Task | A
[Task](https://help.gladly.com/docs/what-is-a-task) on a Customer's
profile | Yes | Yes | Yes | No | No |
| Topic Change | A
[Topic](https://help.gladly.com/docs/what-are-topics) added or removed on
a Conversation | Yes | Yes | No | Yes | No |
| Twitter (decommissioned as of 04/20/23) | A
message sent/received via the
[Twitter](https://help.gladly.com/docs/setup-and-configure-twitter-direct-messages)
channel | No | Yes | No | Yes | No |
| Voicemail | A Voicemail received | No | Yes |
No | No | Yes |
| WhatsApp | A message sent/received via the WhatsApp
channel | No | Yes | No | No | No |
### Chat Message
Content of messages sent between Gladly and customers through Gladly Chat.
### Conversation Status Change
Record of a change in the status of a conversation.
### Customer Activity
Information about activities customers participated in, for example,
emails they received, issues in another system, or customer satisfaction
surveys they answered.
These can be created through the API to bring in information from other
systems.
Adding an activity to the customer timeline is not customer facing.
For example, posting an email activity to the timeline does not send an
email to the customer.
### Email
Content of emails sent between Gladly and customers.
### Facebook Messenger Message
Content of messages sent between Gladly and customers on Facebook
Messenger.
### Instagram Direct
Content of messages sent between Gladly and customers on Instagram Direct.
### Note
Content of the note recorded in Gladly.
### Phone Call
Information about phone calls that took place between Gladly and
customers.
### SMS Message
Content of SMS text messages sent between Gladly and customers.
To send SMS messages to customers through the API, see [Send
SMS](https://developer.gladly.com/rest/).
### Task
Interacting with tasks through the conversations API is deprecated. Use
[Tasks API](https://developer.gladly.com/rest/) instead.
### Topic Change
Record of an agent adding or removing a topic from a conversation in
Gladly.
### Twitter (decommissioned as of 04/20/23)
Content of messages sent between Gladly and customers on Twitter.
### Voicemail
Information about voicemail left by customers in Gladly.
### WhatsApp
Content of messages sent between Gladly and customers on WhatsApp.
name: Conversations
- description: >
A task is a way to create and do internal follow-up work for a customer
within Gladly. Tasks have a due date, an assignee, a description of what
is needed for a customer, and can be commented on. These can be created
through the API to assign items to work within Gladly.
name: Tasks
- description: >
The collection of Message Automation APIs are used to facilitate
communication between a Customer via a Gladly channel and a 3rd party
Automation service, such as a chat bot. These APIs allow an Automation
service to interact with a Customer as well as close a Conversation with a
Customer or route a Customer to an Agent. Subscribe to the [Webhook
Event](https://developer.gladly.com/rest/) `AUTOMATION/MESSAGE_RECEIVED`
to receive inbound messages. **Note** The Message Automation APIs are
currently in a private beta and attachments are currently not supported.
Please contact your Customer Success Manager for access.
name: Message Automation
- description: >
Export API is a simple, comprehensive, file-based data export. You can
export the lifetime of your customers' conversations in Gladly to a
central data repository such as your data warehouse or data lake. You can
export all communications successfully delivered within a specified date
range. The export date range could be the past hour, the past 24 hours,
or a custom data range. Please note, for one-time exports covering a
period greater than six months, a service fee may apply.
Job results can be deleted once downloaded. Delete will remove all result
files along with the job metadata. Files older than 14 days are removed
from Gladly and jobs older than 14 days are not available from the API.
If you discover that you need the deleted files later, please contact
Gladly Support to regenerate them for you.
### SCHEDULING EXPORT JOBS
You can schedule a one-time or repeating - hourly or daily - data export
job. By default, each organization has a daily export job configured. To
schedule a one-time job or change the job frequency, please contact Gladly
Support.
name: Export
- description: >
A **Webhook** is a way to send notifications about Gladly events as a POST
request to the endpoint of your choice.
name: Webhooks
- description: >
An **Agent** represents the user profile of a person who helps customers
in Gladly.
The API allows you to lookup Agents who participated in conversations with
customers.
name: Agents
- description: >
A **Public Answer** in Gladly represents a consumer-facing Answer.
Answers API allows you to search and retrieve Public Answers (created
directly in the Gladly UI), which you can display in the Glad App
web widget, use to build your website's help center/FAQ page, or publish
on any page on your website.
This API can be used without an API token because it only provides access
to
public content. You may also work with Gladly Support to
enable [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
access so the API can be used directly from client-side javascript.
### How a user creates a public answer in Gladly
### How that answer is searched and displayed on the Glad App Web widget
name: Answers
- description: >
A **Customer** in Gladly represents information about a customer of your
organization including their profile, contact information,
notes, and transactions.
Customers API allows you to add, update, and get customer profile data.
### Error Handling
Id, mobile phone number, and email address must be unique across customer
records. 409 errors returned will
include details on any conflicts, such as a field being taken.
Additionally, errors may be returned due to customer profiles being
merged. If a customer has been merged into
another, requests to get a customer by id will return 301 errors
specifying the new id of the customer,
and requests to update a customer by id will return 404 errors.
name: Customers
- description: >
Communications API enables you to programmatically send SMS messages to
your customers and receive messages from a
custom channel integration.
### Agent View
### Consumer View
name: Communications
- description: >
A **Report** in Gladly contains metrics that you need to run the contact
center. Reports API allows you to access Gladly's reports programatically.
name: Reports
- description: >
An **Inbox** receives customer communications in Gladly. The
communications route to the inbox according to channel and destination
endpoint configuration.
For example, all calls to a specific phone number or emails to a specific
address may go to an inbox.
name: Inboxes
- description: >
A **Team** represents a group of Agents. They may handle particular
**Inboxes** or types of work within Gladly.
name: Teams
- description: >
A **Topic** is a way of labeling a conversation in Gladly for specific
business purposes. For example, an agent may apply the topic "Return" to a
conversation where a customer returns merchandise.
Topics are used for reporting and to control various workflows.
Topics can be configured to have a nested hierarchy. For instance, the
topic "Return" could be a parent of "Size" and "Color" child topics. Visit
our [Help
Pages](https://help.gladly.com/docs/principles-of-hierarchical-topics) to
learn more about Hierarchical Topics.
name: Topics
- description: >
An **Event** is something that has happened in Gladly. The Events API
allows you to extract event details from the past 24 hours.
name: Events
- description: >
Freeform Topics allow you to associate granular data like Order Number to
a Conversation. This data can be accessed for analysis via APIs, Webhooks,
and AWS EventBridge. They are powered by custom attributes as you will see
throughout this API, the Conversations API, the Events API and events used
in Webhooks.
Note: These attributes are currently associated to the Conversation entity
only and are therefore different from customAttributes listed under the
Customer entity. See the Customer API for more information on Customer
custom attributes.
name: Freeform Topics
- description: >
An **Organization** contains metadata about your company that Gladly is
configured with.
name: Organization
- name: User Identity
- name: Payloads
- description: >
Gladly **webhooks** are an easy way to send notifications about Gladly
events and have them delivered to the endpoint of your choice, giving you
a streamlined method to trigger associated actions in external systems
that respond to events in Gladly.
Simply choose where to send notifications about events that you are
interested in (e.g. when a conversation is closed), and they’ll be
delivered to the endpoint of your choice.
Configure webhooks using the [Webhooks
API](https://developer.gladly.com/rest/) or the Webhooks Admin Page.
Users with API User permissions can configure webhooks by navigating to
Integrations > Webhooks.
## Securing Webhooks
We provide two methods for your web service to authenticate requests from
Gladly.
We recommend implementing at least one **authentication** option.
### Basic Authentication
For this method you will supply a username and password with the webhooks
`credentials` field. This will be sent with each request. You may
optionally supply a realm if needed.
### Header Based Token Authentication
For this method you will configure one or more HTTP headers with the
webhook's `headers` field. Gladly will send in each request to your web
service.
## Ping Event
Whenever you enable a webhook or update a webhook's URL, we'll send you a
special `PING` event.
Your web service is expected to respond with a 200 status code to this
event. If it does not respond or times out, the webhook create or update
will not succeed.
## Retry Policy
**Effective 6/28/23**
If your service responds to an event with a response code outside the 2XX
range or times out after 15 seconds, Gladly considers that delivery as
failed and will resend the request up to 4 times over an hour. After the
fourth attempt, we will deactivate the webhook and wil notify all API
Users in your organization's environment via email.
To reactivate the webhook, your team will first need to investigate the
issue and make the necessary changes for the webhook to start working
again. Once the issue is resolved, you will be able to re-activate the
webhook via the Settings > Webhooks page.
The following table shows the intervals between each retry attempt.
| Attempt | Retry interval |
| ------- | ------------------------ |
| 1 | 30 seconds |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 1 hour |
## Logs
We provide the last 100 HTTP request logs for a webhook that occurred
during the past month. Logs can take up to 30 seconds to view and require
you to refresh the page.
Each log displays the status, event type and occurred at timestamp for a
given request. You can expand the log for more details about the request
and response.
For more information about webhook logs, please see our [Help
Documentation](https://connect.gladly.com/docs/help-documentation/article/reactivate-deactivated-webhooks/?highlight=webhook).
## Payloads
Gladly payloads are intentionally small: they contain only Gladly IDs and
event names rather than the object/data that has been modified or created
This helps Gladly webhooks perform more quickly when many events occur
throughout the day. This also assists with security, so if you
misconfigure a webhook, it does not send sensitive information to an
outside service.
To retrieve more information about the object in question, you may make an
additional Gladly API call to retrieve the Gladly object. For example, to
know more about conversationId whose status was updated, call the [GET
Conversation API](https://developer.gladly.com/rest/) or the [List Items
in Conversation API](https://developer.gladly.com/rest/).
## Available Events
Please see the [Help
Documentation](https://help.gladly.com/docs/reporting-concepts) for more
information about many of the events listed below.
| Event | Triggered by Gladly
when: |
| ------------------------------|
--------------------------------------------------------------|
| AGENT_AVAILABILITY/UPDATED | an Agent's availability is updated
|
| AGENT_STATUS/CHANGED_ACTIVE_REASON | an Agent's active reason is updated
|
| AGENT_STATUS/LOGGED_IN | an Agent logs in |
| AGENT_STATUS/LOGGED_OUT | an Agent logs out |
| AGENT_STATUS/RETURNED_FROM_AWAY | an Agent returns from away |
| AGENT_STATUS/WENT_AWAY | an Agent goes away |
| AUTOMATION/MESSAGE_RECEIVED | an Entry Point that has been
configured for Message Automation receives an inbound message |
| CONTACT/ENDED | a Contact is ended |
| CONTACT/FULFILLED | a Contact's SLA is fulfilled |
| CONTACT/HOLD_ENDED | a Contact's hold is ended |
| CONTACT/HOLD_STARTED | a Contact's hold is started |
| CONTACT/JOINED | an Agent joins a Contact |
| CONTACT/MESSAGE_RECEIVED | a Message is received |
| CONTACT/MESSAGE_SENT | a Message is sent |
| CONTACT/OFFER_ACCEPTED | a Contact's offer is accepted |
| CONTACT/OFFERED | a Contact is offered |
| CONTACT/OFFER_REJECTED | a Contact's offer is rejected |
| CONTACT/STARTED | a Contact is started |
| CONTACT/TRANSFERRED | a Contact is transferred |
| CONVERSATION/CLOSED | a Conversation is
closed |
| CONVERSATION/CREATED | a new Conversation is
created |
| CONVERSATION/CUSTOM_ATTRIBUTE_ADDED | a custom attribute has been added
to the conversation |
| CONVERSATION/CUSTOM_ATTRIBUTE_REMOVED | a custom attribute has been
removed from the conversation |
| CONVERSATION/NOTE_CREATED | a Note is added to a Conversation |
| CONVERSATION/REOPENED | a Conversation is reopened
| CONVERSATION/TOPIC_ADDED | a topic is added to a Conversation
|
| CONVERSATION/TOPIC_REMOVED | a Conversation's topic is removed |
| CONVERSATION_ASSIGNEE/UPDATED | a Conversation's assignee (inbox
and/or Agent) changes |
| CONVERSATION_STATUS/UPDATED | a Conversation changes statuses
(e.g.: from OPEN to CLOSED) |
| CUSTOM_CHANNEL/MESSAGE_SENT | an outbound message sent using a
Custom Channel |
| CUSTOMER/MERGED | a Customer Profile is merged with
another profile |
| CUSTOMER_PROFILE/CREATED | a Customer Profile is
created |
| CUSTOMER_PROFILE/DELETED | a Customer Profile is
deleted |
| CUSTOMER_PROFILE/MERGED | a Customer Profile is merged with
another profile |
| CUSTOMER_PROFILE/UPDATED | a Customer Profile is updated
(e.g.: name is updated) |
| EXPORT_JOB/COMPLETED | a [data export
job](https://developer.gladly.com/rest/) is
completed |
| EXPORT_JOB/FAILED | a [data export
job](https://developer.gladly.com/rest/) fails to
complete |
| MESSAGE/RECEIVED | an inbound message other than a
phone call is received |
| PAYMENT_REQUEST/CREATED | a payment request is created |
| PAYMENT_REQUEST/STATUS_CHANGED | a payment request's status changes
|
| PAYMENT_REQUEST/VIEWED | a payment request is viewed by the
Customer |
| PING | a webhook is initially created to
verify serivce availability |
| TASK/ASSIGNEE_UPDATED | a task's assignee is updated |
| TASK/CLOSED | a task is closed |
| TASK/COMMENT_ADDED | a comment is added to a task |
| TASK/CONTENT_UPDATED | the content of a task is updated |
| TASK/CREATED | a task is created |
| TASK/DUE_DATE_UPDATED | the due date of a task is updated |
| TASK/FOLLOWER_ADDED | a follower is added to a task |
| TASK/FOLLOWER_REMOVED | a follower is removed from a task
| TASK/REOPENED | a closed task is reopened |
name: Summary
- description: >
**Customer Lookup** allows you to provide a web service to search and get
customer profile data and transactions.
To support Customer Lookup, your organization will deploy an adaptor
service (aka Lookup Adaptor) running on your network that implements the
Lookup API.
From there you can can connect the service to internal systems providing
customer and transaction data.
### Overview
Building a Lookup Adaptor will allow you to showcase extended customer
profile information and actions in Gladly. For example, you may extend the
customer profile in Gladly with loyalty points and lifetime value to
assist with VIP routing. You can also display historical orders in Gladly
to allow agents to view frequently used directly in Gladly without having
to go to another system. You can even extend Gladly with Actions so that
agents can cancel orders or award loyalty points directly in Gladly!
On a high-level, Gladly will perform a request to your Customer Lookup
integration(s) to retrieve extended information from your system(s) about
a Customer Profile in Gladly.
To ensure performance, Gladly recommends that your Customer Lookup
integration(s) be able to respond back to the Gladly POST request in < 5
seconds. Gladly will terminate the request in 15 seconds if it receives no
response from your integration(s). Please note that if one Customer Lookup
integration times out / responds with an error that Gladly will consider
this an error for all Customer Lookup integration(s).
### Sample code
Sample code for building a Customer Lookup integration can be found
[here](https://github.com/gladly/lookup-practice).
### Architecture, Setup, Authentication, Sample Requests and More
A detailed overview of Lookup Adaptor architecture, requests, resposnes
and more can be found
[here](https://help.gladly.com/developer/docs/lookup-adapter-introduction).
name: Customer Lookup
- description: >
As we evolve the Gladly API over time, changes will be either added to the
current version of the API (i.e. **[backwards compatible
changes](https://developer.gladly.com/rest/)**),
or result in a new version that you will need to integrate with afresh
(i.e. **[non-backwards compatible
changes](https://developer.gladly.com/rest/)**).
## URL Path Versioning
The various versions of the Gladly API will be differentiated via global
versioning, with the relevant version number reflected within the path
parameter of the URL:
https://organization.gladly.com/api/v{major-version-number}/{resource path}
## Backwards Compatible Changes
For the most part, changes to the API will be backwards compatible, such
as adding resources, additional fields to response objects,
new value types for enums, or expanding a validation constraint to be more
accepting.
Ensure your client can gracefully handle or ignore unfamiliar fields and
values so it continues to operate smoothly over the lifespan of an API
version.
## Non-Backwards Compatible Changes
Versions will be upleveled when a non-backwards compatible change occurs.
This should not happen often, but can occur in the case of:
- a field being removed from an object
- a resource path no longer being supported
- changing the type of a field
- adding a new required parameter for a resource
- constricting the validation parameters for a request
These will only occur when absolutely necessary and a summary of the
changes from version to version can be viewed in the release notes.
Previous versions will be supported for a period of time before being
removed after providing ample advanced notice.
name: Versioning
- description: >
Wherever possible, Gladly uses standard HTTP status codes to signal the
success or failure of a call.
Generally speaking, `2xx` statuses indicate success, `3xx` statuses
indicate the client must take further action such as redirection,
`4xx` statuses indicate an error with the input supplied by the client,
`5xx` statuses indicate an unexpected error from Gladly servers (these
will be rare cases).
## Common Status Codes
| HTTP Status | Description |
| ----------- | ------------------------------------------------- |
| 200 | Success with results in response body |
| 201 | Resource created |
| 204 | Success with empty response body |
| 301 | The resource location has moved |
| 400 | API usage error |
| 401 | Authentication not provided |
| 403 | User does not have persmission to access resource |
| 404 | Resource is not found |
| 429 | Rate limit reached |
## Programmatic Remediation
In the case of a `400` response, there will be a structured list of
`error` objects that will provide information to correct the error.