That's correct. The web messaging feature doesn't make use of the standard platform's interfaces (Platform API and WebSocket notifications); it has its own bespoke interfaces.
Interesting... I've just opened like a dozen new browser tabs, and the more I look into it, the more questions it raises... I just deleted a really long paragraph filled with questions. 
But I guess I'll just have to take it page by page and see if I can make sense of it all. It definitely seems less tutorial-like, more encyclopedia-style reference material for people who already know what they're doing, but now that I at least know the correct name for the thing I can begin digging for videos and try different questions with the AI and all that. Like I said, thanks for pointing me in the right direction.
Hi there.
Not meaning to be a jerk, but would you mind posting that in a separate thread? It sounds like a widget setup issue (and I didn't set up our widget, so unfortunately I'm not much help, sorry). That's unrelated to my issue. For me, the widget sends stuff to Genesys... but the question is how to receive and send responses from my app (completely unrelated to your problem). I'm still decoding the paragraphs of assumptions in the docs I'm pouring over, cuz it's definitely not a step-by-step process so much as a memorize-it-all-and-pray-it-clicks-one-day type deal... like for me, I expect I'll have to get on a meeting with the co-worker who built the chat widget to see if he can decipher what it means by "deployments" and junk like that... these instructions were clearly designed for people who have already cracked the "which script tag do I load to get the new SDK" type nooby questions II expect to be posting more questions here related to my stuff, so I would prefer to avoid confusion by introducing a second problem, if that's okay.
Sure, I'm happy to post in a separate thread.
1 Like
The user types their messages into the widget and sees incoming messages in the widget. This is base functionality; you don't have to build that. There are limited options to interface with the messenger though: https://developer.genesys.cloud/commdigital/digital/webmessaging/messengersdk/SDKCommandsEvents/messagingServicePlugin.
If you don't want to use the widget and want to build your own UI to send and display messages, then you should use the web messaging guest api https://developer.genesys.cloud/commdigital/digital/webmessaging/websocketapi.
Hi Tim. I've moved my post - getting the Webchat widget properly connected to my client's Genesys ORG so that an agent will see the message in queue - to this location: Webchat Widget V2 Not Delivering Chat Request to Genesys Cloud Queue per the original poster's request. I'm just trying to get the "out of the box" webchat functionality working and not having any luck.
Thanks!
I wasn't replying to your removed post. I was replying to LighthouseMike's post in this thread.
Ohhhh... so it's not really an API so much as some kind of plug-in-like, "widget-to-widget", pre-built chat system. That's not what we had in mind, so I will look into the "Guest" API. btw, as I was digging into the docs, I saw what looked like a whole mess of instructions on setting up another OAuth run (getting codes, trading codes for tokens and so on)... who is Guest (and will logged-in users need to authenticate with them as well as with Genesys)? Or maybe Guest is not a company or API, but a user role or something...
It sounds like you're referring to authenticated web messaging. That's an optional feature and not one you should implement unless you have a specific use case for it.
The "guest", in any web messaging context, refers to the end-user that is attempting to communicate with an agent.
1 Like
Gotcha. I thought it might be something like that. Yeah, we're trying to create something like the Genesys Cloud interface has, where chats come in and users can respond to them, there might be multiple chats, chat transfers, etc... looking at the page for the guest API, it's all about starting things from the customer side of things, creating a session and all that... but how do users know that a session has started? So like okay, let's say I get the config info from our chat widget (which looks like it has to be passed to our app, which probably means one more DB table and all that lol). Let's say I have the info set up - even if I'm just using the "receiver widget" (if there is one)... will I get a pendingSession event? Wait, that can't be, cuz that's a WebRTC SDK thing... will I need to set up a notification? No wait, that's a Platform SDK thing. Apologies for the "thinking out loud" here... how will users of my app become aware of the fact that a message has come their way? Will the receiver widget play a sound and pop up or something?
EDIT: PS: Thank you very much for your time. You've answered all my crazy questions today lol.
Is your custom app that you're building something for Genesys Cloud agents to use? Or is it something your end-customers, the "guest", will use? Both roles will obviously be involved in conversations, but which side is your custom app for?
This is important because you cannot customize or rebuild the agent side of web messaging. It's still a conversation and you get the media type agnostic behavior from all the normal Platform API endpoints (e.g. pickup, transfer, disconnect), but you have no way to interact with the web messaging media (e.g. send/receive messages). That implementation remains private and you must use one of the Genesys-provided UIs to handle web messaging media on the agent side.
In contrast, the guest API provides the full functionality for the guest side of the conversation. You can build your own guest interfaces from the ground up without using anything but the WebSocket-based guest API (and a solitary Platform API REST endpoint for message history...).
I see; it sounds like we have the wrong chat API. Yes, this is for users, people handling calls. The chat widget for "guests" is just a means to an end, a way to test our code. So is what we're looking for called something else? (Chat, Web Chat, etc.?). I'm not talking about the "guest" side of things at all.
I put out a query to the web messaging team just to be sure a new feature hadn't snuck out, but the good news (for you) is that one did! There actually are Platform API endpoints for the agent side now. There's no documentation for how to use them other than API Explorer, but I've asked that they be created. I would suggest also submitting an idea on https://genesyscloud.ideas.aha.io/ to request that the agent web messaging APIs be documented. Customer requests get a lot more priority than internal requests.
So here's the information I got. I don't have any guidance to share on exactly how to use them though. You'll have to do a little trial and error. If you get stuck on something, post what you can't figure out or what error you're getting and I can ask someone from the web messaging team to join the conversation.
- Send message POST /api/v2/conversations/messages/{conversationId}/communications/{communicationId}/messages
- Send typing indicator POST /api/v2/conversations/messages/{conversationId}/communications/{communicationId}/typing
- Receive message v2.users.{id}.conversations.messages
- Receive typing indicatorv2.users.{id}.conversations.inbound.typing.event (I don't know if this actually works; it's marked as preview)
1 Like
Okay, I knew I wasn't going crazy 
But seriously though...
- Thank you for the links!
- Yes, I will definitely recommend documentation for these awesome new features you guys are creating. I didn't know you had an ideas page like that, but IMO that is a really good idea that totally deserves a customer request (and yeah I get what u mean about customer requests vs. internal requests too, lol ).
- And again, thank you very much for taking the time to walk through this with me. I get you probably get a zillion "I can't get ___ working" type posts to deal with, so I really appreciate that you were able to bear with me and help figure this all out.
1 Like
Hey, one last question: For the POST function, how do I get a "communicationId"? All the docs say for that parameter is "communicationId" (no further explanation). When I use the GET endpoint to list chats, I can get a "conversationId", but that is just one of two parameters. Not the first time the docs have gotten all mysterious on me, but it would be nice not to spend all day hackn'nguessing like I did the last hour of last nite.
And speaking of docs, I tried to "submit an idea" on that other site, but it didn't like my login... unrelated to my main question, just an FYI. But I did try.
This post covers it pretty well. The short answer is that the ID you're looking for is never called that where you get it.
The ideas site uses the same login you use to submit/view Care tickets. Not everyone will have that. If you do have one of those accounts and it's not working for the ideas site, I believe Care can help with that.
Interesting... so, from the notification, I JSON-decoded the data and eventually narrowed it down to I think eventBody.participants[the one with purpose=customer].peer. This mysterious "peer" field is the only ID in the entire gargantuan object hierarchy that it would kinda-accept. However, with every request I try (not just the one with purpose=customer) I'm getting "Bad request: Messages may only be sent for connected communications" (or sometimes it'll say "non-external" instead of "connected"). So... yeah, back to the infinite loop of trial/error/Duck/Duck/Go
But let me ask you this... is there a place with complete documentation/explanation of the wildly complex objects we get back from Genesys? I mean... okay, if they have a thing called a communication ID, but they call it a session ID when it's a part of ISomeInterfaceA but a peer when it's a part of ISomeotherInterfaceB, and all the docs do for the description is repeat the name they gave it, "communicationId"... clearly, somebody somewhere knows more about what all these things represent than its name. I know the guys who built it like OOP, as a lot of the docs for return values just list an interface name. But just mentioning the return type is utterly useless unless you happen to have a manual documenting all the different interfaces. I forget what the one for this POST call was, ISomethingOrOtherLolIdk but you get the idea. If I go to the docs and all they have for the return type is "IFoo", then I can look up what IFoo's fields are; if a parameter is an IBar, I should be able to look up IBar and find out what they need/want there. At this point... what's the point of a communication ID? It's a chat, the chat is still in progress (still "connected" by the standard definition of the word), so why would it want some other ID? It would be like me writing a function and here are my docs:
void sendChat(string foo, string bar, string baz);
Parameters:
- Foo: foo
- Bar: bar
- Baz: baz
Returns: IVaguesville
How the heck could you be expected to understand what "foo", "bar", and "baz" mean when all you have to go on is the data type? I bet I'm missing some kind of "extended" documentation someplace, that explains some of the more cryptic, mysterious aspects of Genesys stuff... or is that wishful thinking?
That probably means you're not choosing the right participant or segment/session. It needs to be "your" session, so the participant has to be the user for which the auth token was issued. There can be more than one session per participant; the one you want should be the one that has a start date and no end date.
The schema itself is always documented in API Explorer. That's not to say that will always answer all your questions, but that's officially the complete schema definition. You can find additional documentation for specific models and endpoints throughout the site, categorized by functional area. For example:
- Conversation API conversation data model https://developer.genesys.cloud/routing/conversations/
- Analytics API conversation data model https://developer.genesys.cloud/analyticsdatamanagement/analytics/detail/conversation-data-model
The specific documentation you're asking for in this case to understand the communication ID is what's missing. There's no way to know that from what's in API Explorer alone.
One good approach to replicating functionality from the Genesys Cloud UI is to inspect the network console in your browser when you do the thing you're trying to replicate. That will show you the API endpoints and exact payloads being sent. For example, look at the request used when sending a message and what IDs it's using. Then fetch that conversation using your API requests and see what piece of the conversation it got that ID from.
I didn't see any end dates in the messages, but I'll just try all the participants and see which one sticks. I don't know anything about an auth token tho... I mean when I logged into my app, there's the usual Genesys access token... is that it? In that case it would be purpose=agent, not customer...?
Yeah, what they call the "schema" is just the object's structure - and I can get that from the browser's developer tools. I guess it's nice that they gave us a way to confirm that the structure we get from Genesys matches the expected structure or something... but structure !== meaning, and even in the examples they don't mention things (I always laugh when I see code in their examples like var communicationId = "communicationId_example"; // communicationId - yes, it's called a communication ID, and.......? it was definitely the meaning, not the structure, that I was more interested in getting at. Pity that's missing from the docs. But I'll definitely check out those "data model" links - I bet those will help in understanding the design of things more clearly.
Yeah, that's usually my last resort (remember a few months ago I stumbled on an undocumented API and posted about it? Yeah... playing hacker is fun ). But thanks for the reminder. Actually, I think that'll help with things like ending and wrapping up a chat.