Figuring out which Intercom app triggered the configure flow for my Messenger App

#1

I’m trying to figure out which Intercom App (Organization) triggered the configure flow, so that I can render the correct sheet for that organization.

Our use case is this: We have a multi-tenant system where each organization has its own URL. We want to render a sheet which is specific for that organization, and the idea is that there exists a 1-1 mapping between the Intercom organization and our organization.

The problem we have today is that as far as I can see, there is no way of telling which organization the request comes from, only the user that triggered it. Other integrations seem to rely on the email field today, but in our case the email is not unique across our entire system, only for each tenant. (This is similar to how Slack does it) There is a team_ids field, but this does not map to anything on our end. I’m also confused as to why this is represented as an array, when you are triggering the Messenger App in a specific team’s messenger, not for all the teams you belong to.

Is there a way to reliably link the intercom organization and our organization, perhaps something which is exposed through the install flow which we haven’t been able to test yet?

Thanks for all your hard work so far!

1 Like

#2

Thanks for the question! Are you using your app on the Messenger home or in a conversation? Of the app is in a conversation then you’ll have the conversation id as part of the context. You can use this to fetch the conversation via the API and the app_id (the organization) will be available there.

1 Like

#3

We’ll most likely be using it in a conversation (though on the home could be a useful feature addition later I think), so your suggested solution could work. Thank you!

0 Likes

#4

Glad to hear it’ll work in the short term. We’re working on better (and more) context in all the requests so look for those changes in the next few weeks. :slight_smile:

0 Likes

#5

We’re in a similar situation. Our app will be used by our users’ customers. To get a conversation object, I should use an access token. I think I need to use my user’s access token but I don’t know yet who this is. I know app_id and under user object’s app_id (I’m not sure they should be the same, for example; app_id can be the messenger app’s id and user object’s app_id can be the our user’s intercom app_id).

I think I need to use that end-point: https://developers.intercom.com/reference#get-a-single-conversation

which access token should we use?

Do we get app_id when OAuth process is handing? In this way, we can put app_id to out database when authentication is being established and easily match which app we use.

0 Likes

#6

@volkan You’re right that you will need a token to access the API on behalf of your users but you do not need to store the user’s Intercom workspace (app_id) value. During the course of the Oauth step, once the user grants access you will get a response from Intercom with a code. You will then make a request to our https://api.intercom.io/auth/eagle/token endpoint with that code to get a token back for that user. This is the token that you can store on your end to then access our REST API. All of this is detailed in the docs here.

0 Likes

#7

I think I see a potential “problem” then, consider this case:

The Intercom Team X consists of users A, B and C. User A installs the Confrere messenger app and we store the access token for user A on the correct organization. So far so good.

Now user B is talking to a potential lead and wants to have a video conversation. They select the Confrere app and attempts to add it to the conversation. On our end, we get a configure call with the conversation id, and the user object, consisting of the email of user B. However, we have no way at this point to know which organization we need to fetch the access token of user A from, seeing as the configure callback does not contain any information about team X, nor user A. We could look up the conversation id, but for that we need to identify the correct access token to request that information with.

It would be easier if the configure call contained the app_id, and when the user installs the messenger app, we get an access token, as well as a way to fetch the app_id of the user which installed the messenger app. Then when we get the configure call, we could easily look up the app id, find the access token, and request any information we desire to render the canvas back to user B.

Makes sense?

0 Likes

#8

I could get the conversation object but I can’t find any organization information in there. Am I missing something? I used that end-point:

https://api.intercom.io/conversations/xxxxxxxxxx

Maybe it’s better to put here our situation.

We have customers and our customers use our tool to get information from their customers. We don’t know who their customers are. Now, this getting information part will be made by Intercom apps.

When a new conversation starts, we should know which organization (actually our customer) and its customer (we don’t have any db record for this customer). After that, we can get the values from Intercom app and update our customer’s intercom account fields for our customer’s customer.

Example: Jeff is our customer. Jeff has a customer, Jane. We don’t know Jane. Jeff starts our Intercom app with Jane and Jane put some info in it. We need to get that info and update Jane’s record in Jeff’s Intercom account.

Is this possible?

0 Likes

#9

Hey @volkan and @daginge :wave: Zach from Intercom here!

When someone in an organisation installs the app from the App Store, the access token that’s stored will represent the installation for that App. You shouldn’t need to provide the app_id each time whenever somebody configures/initialises the card from within that organisation.

However, it’s worth noting that when you make calls to the REST API, whoever installed the app initially appears to make these calls and is associated with the actions from these. There are certain calls (such as those using the Conversation API) where you can provide the admin_id in order to make actions appear as if it were from that specified admin. You can retrieve this information to use, alongside the app_id if you need it, in the initial POST request which Intercom will send to your configure-URL:

{
  app_id: <string id_code of the app using the card>,
  admin: <Admin object of admin who is performing configuration>,
  context: <Context object>
}

More on the configure flow is here. Let me know if this helps :+1:

1 Like

#10

Hey Zach!

The problem I’m facing is that I have no way today to match the access token I get from Intercom to any common id on the configure flow. I would need some common id from the installation flow (access token, app id, something else) which is also sent on the configure flow POST requests.

If you see my original use case again, we have a multi-tenant application (which we call organizations), where each organization can have their own Intercom integration. Since all configure flow POST requests for every organization comes to the same endpoint on our end, we need a way to map that request to the correct organization on our end.

I would assume this is the app_id. Do we know the app_id from the install flow? Or is there a way to fetch the app_id for a given access token so that we can store it for that organization and use that to match what organization the configure flow is for?

I would be happy to have a chat on video with you about this if that helps in clearing things up!

1 Like

#11

Hi @volkan and @daginge hopefully I can shed some light on both context and multi-tenet in one response using @volkan’s example about Jeff and Jane…

Let’s assume:

  1. This is a Messenger App that is being shown in a conversation with an end user.
  2. Jeff is a customer of @volkan’s who uses Intercom and is using @volkan’s messenger app.
  3. Jeff is the teammate in Intercom who is having a conversation with Jane.
  4. Jane is the end user of Jeff’s product.

The configure request will hit @volkan’s endpoint with the following.

{
  "app_id": <Jeff's Intercom workspace ID>,
  "admin": <Details about Jeff's Admin object in Intercom>,
  "context": <Context object with conversation details> 
}

app_id

This is the id of the workspace that Jeff authenticated when doing the OAuth flows as part of installing @volkan’s Intercom Messenger App. Jeff can have multiple Intercom workspaces but when he installs @volkan’s app he’s explicitly granting access to just one Intercom workspace.

@daginge, the token that is returned is linked to just this workspace. During the OAuth flow (receiving a code and then trading that code for a token) you won’t be shown this app_id in any requests or responses but because the token is linked to just that one workspace you can immediately use our REST API to fetch all the details about the workspace and admin through the /me endpoint, detailed here.

admin

This is the teammate in Jeff’s Intercom workspace that is configuring your Messenger App, Jeff in our example.

context

This is more context about where the App will be shown, detailed here.

@volkan, if you’re looking for more information about Jane then you can get that by simply using the conversation_id that is part of the context object and our REST API to first look up the conversation, then grab the user id, and finally look up the full user object.

Hopefully that helps clarify everything. I believe that all the necessary data is accessible but let me know if either of you think I’m still missing something. :slight_smile: I’m always happy to be proven wrong.

4 Likes

#12

Thanks for the detailed answer @jeff I think /me end-point solve our problem.

After our customer (Jeff in the example) follows OAuth process I’ll use /me end-point with access token and get app_id from it. I’ll keep the app_id in the db. Later when a new conversation starts, I can match app_id from the conversation and our db.

1 Like

#13

Thank you! The information about where to fetch the app_id at install time was what I was looking for. Now we have a way of connecting the configure and initialize flow calls to a unique organization on our end.

1 Like

#14

This is the crucial part. Thanks for the clarification @jeff! The link to the details isn’t valid anymore and I couldn’t find this in the docs anywhere. Would be good if this can be added. I think this a question pretty much every Intercom app developer faces if they try to publish in the marketplace.

0 Likes

#15

Hey @tobi - the link was broken on the post here, fixed it now :slightly_smiling_face: Cheers for the heads up!

1 Like