Learn how to use Bettermode's API & Webhooks to build custom apps.
API & Webhooks
Start Building
Automating a workflow or syncing data? Build a custom app using our GraphQL API, Webhooks, and Liquid template engine that enables custom script injection.
Use GraphQL API and form requests
GraphQL is an application layer server-side technology that is developed by Facebook for executing queries with existing data. Clients form requests (called queries and mutations) using the GraphQL query language, and the GraphQL server executes the request and returns the data in a response. Check out Bettermode’s Developers Guide to learn more about Bettermode’s GraphQL. Use Webhooks to automatically send data to another source
A Webhook is an HTTP request, triggered by an event in your Betermode Community and sent to a destination system, often with a payload of data. Webhooks are automated, in other words, they are automatically sent out when their event is fired in the source system. Check out Bettermode’s Developers Guide documentation to learn more about Webhooks. To learn more about Webhooks, read more about it in Bettermode’s Developers Guide. Get started with GraphQL API Tutorials
Get started with some basic actions of Bettermode GraphQL API. GraphQL is a query language and a runtime system. For our customers’ convenience, we are publishing detailed tutorials on how to use Bettermode GraphQL to perform some basic actions via API. To access these tutorials, please visit the Developers Guide page on our website. List of some of the available tutorials: Create Member Create Post Create Post Type Create Space Custom Profile fields Invite Members Retrieve Members Retrieve Spaces Manage Space Membership Update Member Space Notification Settings Update Member Upload Files Upload Images Verify Member Migrate content to your site using API
Follow the steps below to migrate content to your Bettermode site using Bettermode's API: Step 1: Generate a Guest Access Token: The first step to start using Bettermode's GraphQL API is generating a guest access token. Here's a sample query that you can use: Copy query { getTokens(networkDomain: "community.bettermode.com") { accessToken role { name scopes } member { id name } } } ❗Important Note: Please replace networkDomain value with your own domain value. Once the query is completed, it will return a result similar to the screenshot below: By following these steps, you will be able to create posts on your site and migrate data to the site by automating these queries and mutations. Step 2: Generate a User Access token: Once you have a Guest access token, you can use it to create a User Access token that's required to perform different queries, mutations, etc. A User Access token is generated using a member's E-mail address or username and password. To generate a User Access token, you need to pass the access token (provided in Step 1) in the header with the following format: Copy Authorization: Bearer {accessToken} Here's a sample query that you can use: Copy query { loginNetwork( input: { usernameOrEmail: "bettermodeuser", password: "bettermodepassword" } ) { accessToken role { name scopes } member { id name } } } ❗Important Note: Please replace 'bettermodeuser' with the e-mail address or username and 'bettermodepassword' with the password of the member. The above 'query' will generate a user access token for you that can be used for a variety of queries, mutations, etc. Here's a sample result that you can expect. Step 1 & 2 are also covered in a video tutorial here- How to generate Bettermode Guest and User Access token Step 3: Creating a post using "createPost mutation" Using the access token from Step 2, we can use createPost mutation to create a post in a specific space. Here's a sample mutation that needs to be used: Copy mutation { createPost( input: { postTypeId: "insert postTypeID", mappingFields: [{ type: text, key: "title", value: "\\"This is where title goes\\"" }, { type: html, key: "content", value: "\\"<p> this is where content goes</p>\\"" }], tagNames: [], attachmentIds: [] }, spaceId: "insert Space ID" ) { attachmentIds createdAt hasMoreContent id imageIds isAnonymous isHidden pinnedInto postTypeId repliedToIds repliesCount shortContent slug totalRepliesCount } } ❗Important note: Please replace 'postTypeId' with the id unique to your site and 'spaceId' with the id you'd like to add. Depending on the fields requested, you will receive a result similar to the one below: By following these steps, you will be able to create posts on your site and migrate data to the site by automating these queries and mutations. Migrate members to your site using API
To migrate members to your Bettermode site using Bettermode's API, follow the steps below: Step 1: Generate a Guest Access Token: The first step to start using Bettermode's GraphQL API is generating a guest access token. Here's a sample query that you can use: Copy query { getTokens(networkDomain: "[community.bettermode.com](<http://community.bettermode.com/>)") { accessToken role { name scopes } member { id name } } } ❗Important Note: Please replace networkDomain value with your own domain value. Once the query is completed, it will return a result similar to the screenshot below: Step 2: Generate a User Access token: Once you have a Guest access token, you can use it to create a User Access token that's required to perform different queries, mutations, etc. A User Access token is generated using a member's E-mail address or username and password. To generate a User Access token, you need to pass the access token (provided in Step 1) in the header with the following format: Copy Authorization: Bearer {accessToken} Here's a sample query that you can use: Copy query { loginNetwork( input: { usernameOrEmail: "bettermodeuser", password: "bettermodepassword" } ) { accessToken role { name scopes } member { id name } } } ❗Important Note: Please replace 'bettermodeuser' with e-mail address or username and 'bettermodepassword' with the password of the member. The above 'query' will generate a user access token for you that can be used for a variety of queries, mutations, etc. Here's a sample result that you can expect: Step 1 & 2 are also covered in a video tutorial here- How to generate a Bettermode Guest and User Access token Step 3: Creating a Member using "joinNetwork mutation": Using the access token from Step 2, we can use joinNetwork mutation to create a Member in a specific space. Here's a sample mutation that needs to be used: Copy mutation { joinNetwork( input: { email: "[email protected]", name: "Name of the user", password: "TestPassword", phone: "+919213849901", username: "username-of-the-user" } ) { accessToken refreshToken } } Depending on the fields requested, you will receive a result similar to the one below: By following these steps, you will be able to create user profiles on your site and migrate data to the site by automating these queries and mutations. Best Practices while generating App Access Token
The app Access token allows the site admins/developers to perform actions on behalf of a specific member or bot account. It works as if the actions are being performed by that member, and there’s no need to know the email address and the password of that member to do it. To understand the process of Generating the App access token for a specific site, please follow the steps shared in our Guide here: App Access Tokens. Here are some of the best practices to ensure that you’re not running into any issues while generating the Access Token: Please ensure that the App is published in the site they intend to make API Calls for. For Example, in the example below, if the API calls need to be performed for “community2.blogha.com”, it should say ‘Unpublished’ right next to the site details indicating that the site is published. Please ensure that the app is installed on the site under the Apps section. The app is not automatically installed after it’s published. The request that is being sent should be a post request. If you use any other request type, it won’t work. Please ensure that the entityID and the networkID are the same. If impersonateMemberId is left blank, an Access token for a bot will be created. The Client Secret should never be shared publicly. Common App Access token Errors
Bettermode allows apps to perform actions on behalf of a bot account or a specific member of the site using API. Bot accounts can perform all actions that a site admin can perform. Here are some of the most common errors that you might encounter when you’re trying to generate an access token to perform actions through the App: “Forbidden” Error: If you’re trying to make an API call using an app that is not published OR installed on that specific site, the Forbidden error is returned. How to Resolve the Issue? Please ensure that the site is Published within the App. To check this, please go to the Developers Portal, log in and Open the App. Inside App, check if you see ‘Unpublished’ right next to the name of the Site. Please see the example below. As you can see in the screenshot below, right next to CJ’s Site, you can see a red-colored ‘Unpublished' button. That confirms that this App is distributed to the correct Site. Please go to your Profile Picture on the top right→ Administration→ Apps and check if the newly created App is installed or not. For example, an app was created called “Webhooks Testing” and this App is visible in the ‘Apps’ section. If you’re still facing issues, please post about the issue in Support Space on the Bettermode Site with the following Information: Name of the App created and used to generate an App Access token. URL of the site for which the App is Published Screenshots of the call they’re making. Screenshots of the Developer Portal confirming that the App is published. To access the Developers Portal, please follow the steps in Point 1 above. ‘Unauthorized’ Error If you are receiving the Unauthorized Error, it means that the call doesn’t have the correct format. How to resolve the Issue? Here’s where you can learn more about how to properly call the endpoint to generate the token: App Access Token An access token needs the following Information: networkId- To get the correct networkID of the site, go to Developers Portal, log in and open one of the Apps. On the left side, go to Test & Publish, and you will be able to see the networkID of the site right below its URL. Here’s an example: entityId- It’s the same as NetworkID. impersonateMemberId- ID of the members or the bot that needs to be impersonated. To find the ID of a member, go to Profile→ Administration→ Members and you will see the id for all members. clientId & clientSecret- - Go to App(inside Developers Portal)→ Credentials If you’re still facing issues, please post about the issue in Support Space in the Bettermode Site with the following Information: Name of the App created and used to generate an App Access token. The Site URL for which the App is Published Screenshot of the call they’re making. The app {AppID} cannot access the network {networkID} This error means that the App is not installed on the correct Site. How to resolve this issue? We need to make sure that the newly created app is published in the correct Site. Please go to Developers Portal, log in and open the App in question. On the left side, go to Test & Publish and you will be able to see the networkID of the site right below its URL. You can confirm if the networkID is correct. Here’s an example: Most likely, this is the reason behind the Issue. If you’re still facing issues, please post about the issue in Support Space in the Campfire Site with the following Information: Name of the App created and used to generate an App Access token. URL of the site for which the App is Published Screenshot of the call they’re making. Screenshot of the Developer Portal confirming that the App is published. To access the Developers Portal, please visit this URL: Developers Portal The app {AppID} cannot impersonate member{memberID} This error suggests that either the memberID is wrong or the member belongs to a different site, and we’re using an incorrect AppID. How to Resolve the Issue? We need to make sure that the member exists on the site where we’ve installed the app. To check that, please go to Developers Portal, log in and open the App in question. On the left side, go to Test & Publish and you will be able to see the name and networkID of the site right below its URL. You can go to that site using the URL and search if the member exists. Most likely, the member won’t exist. If you’re still facing issues, please post about the issue in Support Space in the Campfire Site with the following Information: Name of the App created and used to generate an App Access token. The site URL for which the App is Published Screenshot of the call they’re making. Id of the member. Screenshot of the Developer Portal confirming that the App is published. To access the Developers Portal, please visit this URL: Developers Portal Use Bettermode's JS(JavaScript) Client
Bettermode's JavaScript client allows developers to effortlessly interact with Bettermode's GraphQL API using Node.js or JavaScript on the back end or front end. To get started and learn more, read this JavaScript Client tutorial in Bettermode’s Developers Guide. Build a custom app using the Developers Portal
Using Bettermode's developers portal, you can build and connect custom apps to your sites. This will allow you to unlock enormous functionalities for your sites powered by Bettermode. How Bettermode's Developer Portal works This initial version of Bettermode's Developer Portal allows businesses to seamlessly use Bettermode APIs and webhooks to build a new app on top of their sites. Developers can create a new app and then publish it on all the sites that they have admin access to. Below are the steps you should follow in order to build and add a new app to your site powered by Bettermode: 1. Visit developers.bettermode.com/portal 2. Use an email address to log in as a developer. Note: Use the email address that has admin access to your site so that you can publish the app to your site afterward. 3. Click on “Create a new app” and insert your choice of App name and Slug. Then, pick the site on which you would like to publish the app. Note: The sites you see in the dropdown are those you have access to as an admin with the same email address used in step #2 above. 4. Now you can start building your app using Bettermode's GraphQL API and webhooks. Note: Click on each item on the left menu for detailed technical tutorials. Note: Click on Credentials in the left menu to access your API keys. ❗ Important: The apps will only be available to the site for which the app has been created. In the future, we'll provide admins with the ability to publish an app that other site builders on Bettermode can benefit from. Related Topics: Bettermode's Developer Platform Developer Portal: Bring Your Site Ideas to Life
Developers Guide
Extensive documentation on how to use SSO, API, Webhook, and much more!