Setup for New Customers
Follow the steps to set up the integration.
Login into the Teams
Go to App market
Click on the app icon on the left bottom.
Install Heymarket app
Search for Heymarket in the search on the left.
Click on the Heymarket app tile.
A new modal will open with the details about the app. Click on the Add to team button to set up.
A new modal will open and will ask you for selecting your team & channel.
Select your team & channel and click on the setup button
Setup Heymarket app
After clicking on the setup button, you will be redirected to the team you have selected to install the integration.
A new modal will appear and show you a few features about Heymarket.
Click on the Save button and it will install a Heymarket tab for you.
After you click on the save button you will see a tab installed in your team and it will ask you to log in.
If you have Heymarket login then you can log in. Otherwise, you have to create a Heymarket account.
Click on the sign-up button from the top right.
Now, you will be redirected to a new page to fill in the sign-up details.
Fill in the details for creating a new account and click sign up.
After filling out the form and clicking on the sign-up button. You will receive a confirmation email.
Check your email and verify it by clicking on Verify Email.
Click on the verify email button.
After your email will be verified, you will see a new modal to set up your Teams integration in Heymarket.
Click on the Get started button.
Now, verify your phone number by entering the 4 digit code you received on your phone.
After verifying it you will land on a new page to set up the integration.
Click on the Setup button to start the Teams authentication process.
Choose the Teams account you want to install the integration for,
Grant permission to Heymarket.
After accepting the permissions access you will be redirected to the page where you can map the Team's channel with Heymarket Inbox.
Map your channel and hit the link channel button.
After you are done with the channel mapping, you can test the integration by just sending a message using our echo test.
Click on the Test Integration button and it will send a message to the mapped channel to confirm that integration is configured correctly.
You will see a message in the mapped Teams channel if the configuration is done correctly.
Now, you are all set to go.
- Please Note that The Microsoft Teams Integration does not currently support messaging to other integration channels at this time.
Setup the integration for existing customer
Sign In to Heymarket
Go to https://app.heymarket.com/account/login to log in or click here.
Enter your email and password to log in.
After logging into the app, you have to connect the app with Teams.
Click on the Administration section in the bottom left of the browser.
Click on the “Integrations” tab to connect the app.
Setup
Scroll down to the bottom of the page until you find the Microsoft Teams app on the page.
Click on the Setup link and it will start the authentication process.
You will be redirected to “authenticate” the application from your “Teams” account.
You will then be asked to choose the account with which you want to connect the “Heymarket app”.
Choose your account. Make sure you are the admin of the team you wish to install the Heymarket app on.
Grant access
After you choose your “Teams” account, The app will ask you to grant permissions. These permissions are required to use the app.
After you click on “Accept”, It will take a few seconds to redirect you to the Heymarket app.
Check installation
Once connected the app in Heymarket will display a “Manage” link
Congratulations, you have successfully connected your “Teams” account with “Heymarket”.
Configuration and overview
Configuration & details
Go to the Heymarket app and then into the integration section and click on Manage under Microsoft Teams
You can now link your Team's channel to a Heymarket inbox.
When you link a channel to a particular Heymarket Inbox then you are going to receive the messages of the mapped inbox to its mapped channel in Teams.
Follow the steps to set up an Teams Channel to Heymarket Inbox Mapping,
- Check the Team from which you want to map the channel
- Select the Channel you want to map
- Select the Heymarket Inbox you want to map with the selected inbox
- Click on Link Channel
Installing Heymarket app
After you have configured the Teams channel from Heymarket, now install the Heymarket app inside Teams to access the features.
Following the steps mentioned in the screen above,
- Click on the Apps icon in the Teams app
- Search for the Heymarket app in the search bar.
- Click on the Heymarket app tile from the search result.
After you click on the Heymarket app tile you will see a pop in your Teams app.
Click on the Add to a team button to install the app in a channel.
Search for the channel which you wish to map to the Heymarket inbox.
Installation Options
Now on the app pop-up page, you have options to install the Bot or Tab or Both at the same time.
Installing the tab will only allow you to message from the tab. The bot install will allow you to message from within a channel.
There are three options available for you to choose between,
- Set up button.
- The setup button will be useful if you want to install the Bot & Tab both at the same time. It will instantly install the bot into the selected channel and it will ask you to configure the “Tab” to install.
- Set up a tab option.
- This will allow you to install only the Heymarket tab in the selected channel.
- Set up a boot option.
- This will allow you to install only the Heymarket bot in the selected channel.
Receive messages in the channel
After you are done with the mapping, you are going to receive all incoming text messages into Teams which are mapped to the Teams Channel.
When an inbound text message arrives in the Heymarket inbox then it will be shown in the Teams Channel like the screen below
Reply to messages from the channel
You can reply to the text message directly from the reply thread. You have to @ mention the bot to reply.
Note
- You have to mention the bot in the reply thread.
- Any message you write into the reply after mentioning the bot will be directly be sent to the contact that text messaged you.
- Do not use the thread to create new Heymarket conversations.
- Private channels are not supported.
Create conversation from the channel
You can start a conversation from inside a Teams channel which is
You have to mention the bot @Heymarket to text message a phone number
When you choose the Heymarket from the hint pop up then you will see the suggested action.
You can select the text action to start a text conversation with a particular contact phone number from Channel.
Here’s a basic example of starting the conversation from the channel,
Notes
Please note when creating a new text message from a channel
- Make sure to put space between Bot name, text, phone & text message.
- There should be no space inside the phone number.
Valid phone numbers:
1(415)877-5122 ✅
1415877-5122 ✅
1(415)8775122 ✅
14158775122 ✅
Invalid phone numbers:
1 (415) 877 - 5122 ( it contains space inside the phone number) ❌
1(415) 877-5122 ( it contains space inside the phone number) ❌
1 4158775122 ( it contains space inside the phone number) ❌
+1(415)8775122 (it contains special characters) ❌
- No special characters are allowed inside phone numbers.
- Country code is important otherwise the phone number will be treated as a Local United States number.
Send SMS to List from Channel
You can also send List SMS from the Teams channel by using the Heymarket commands in Teams.
You have to mention the bot @Heymarket to List send message
While using the List SMS make sure to keep space between the `list` command, `list name`, and text message.
The list name should be in double-quotes.
Here's the example to send the List SMS.
Note: Please do not use rich text editor when sending messages or List SMS.
Heymarket tab for Teams
You can use the Tabs to install the Heymarket Chat widget into teams.
It will give you the same experience as Heymarket application (If you are an existing user of Heymarket).
To add the Tab in teams just click on the plus icon
Now, search for Heymarket in the search bar and choose the Heymarket application,
It will open a new modal and then click on Add button in the new Modal
A new modal will launch and it will show you the details about the Tab, just click on the Save button and the tab will be installed.
Using Heymarket Templates in Teams
You can reply to the conversation using Heymarket Templates from inside the Teams Conversation Thread.
Go to any Heymarket in Teams channel & click on the “Hey” icon from the message extension section.
A modal will be open after clicking the icon button.
It will look similar to the image below
Select any of the templates which you want to send.
After clicking the template, the action will take you to a preview screen.
You can preview the message and also it will allow you to edit the message further by clicking the edit button.
Click done after editing the message and hit the send button to send the message to the customer.
The message will be sent on behalf of the user and it will show the details of the User & the template which was used to send the message.
Microsoft Teams Channel Message URL Generator
This endpoint msteams/channel/urls generates Microsoft Teams channel message URLs for conversations matching specific targets. It's used to create deep links to conversations that can be accessed within Microsoft Teams channels.This section describes the Microsoft Teams Channel Message URL Generator. This tool creates direct links to conversations within Microsoft Teams channels.
Endpoint Details
- URL: /msteams/channel/urls
- Method: POST
- Content-Type: application/json
- Authentication: Required (Bearer token)
Request Body
{
"targets": ["string"]
}
Parameters
| Parameter | Type | Required | Description |
| targets | array[string] | Yes | An array of target identifiers (phone numbers) to find conversations for. |
Response
Success Response (200 OK)
Returns a JSON object containing the Microsoft Teams channel message URLs and related data from the internal integration service.
{
"urls": [
{
"channel_id": "19:vevGx-hC_bZbPqiqEstEaGtL-bL01@thread.tacv2",
"group_id": "a9afa12b-e6-e1ce22490149",
"heymarket_inbox": 1234,
"link": "<https://teams.microsoft.com/l/message/19%3AvevGx--bL01%40thread.tacv2/1756988569966?groupId=a9afa12b-e6cf-467e-8c97-e1ce22490149&tenantId=5bc44c18-390c-48ef-b39e>",
"message_id": "175699966",
"tenant_id": "5bc44c18-3-b39e-22a5bc"
},
{
"channel_id": "19:vevGx-bZbPqiqEstEaGtL-bL01@thread.tacv2",
"group_id": "a9afa12b-e6-e1ce22490149",
"heymarket_inbox": 123455,
"link": "<https://teams.microsoft.com/l/message/19%3AvevGx-NDpxJhC_bZbPqiqEstEaGtL-bL01%40thread.tacv2/175569966?groupId=a9afa12b-e6cf-467e1ce22490149&tenantId=5bc44c18-390c-48ef-b39e-c>",
"message_id": "1756988966",
"tenant_id": "5bc44c18-b39e-22a5b63d5bdc"
}
]
}
Error Responses
| Status Code | Response | Description |
|---|---|---|
| 400 | "bad_data" | Invalid JSON in the request body. |
| 403 | "missing targets" | No targets were provided in the request. |
| 400 | "no inboxes found for team" | The specified team has no configured inboxes. |
| 400 | "error" | A general error occurred (e.g., authentication failure, request processing error, or integration service error). |
| 404 | "no conversations found for inboxes and targets" | No matching conversations were found for the provided targets. |
Example Request
curl -X POST https://api.heymarket.com/v1/msteams/channel/urls \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"targets": ["14155557689"]
}'
Understanding the Required Permissions
We request the minimum amount of access required for the app to function properly. Some of these permissions may appear excessive, such as Files.ReadWrite, but Microsoft has created specific permissions for all types of data, which is why we require these additional permissions to ensure that the app has the appropriate access.
The permissions related to Groups, Channels, Teams, and profiles are used to access the names and IDs of these properties. This information is used to map our inboxes and send/read messages, as well as allowing customers to map the channels they need. We store this data so that customers can use it to map their inboxes.
The Files.ReadWrite.All permission is required to upload or fetch files and content related to MS Teams. We use it specifically to access or upload pictures (MMS) from or in MS Teams.