From 524916c20cebd68b6595b082f58befe9003bea4e Mon Sep 17 00:00:00 2001 From: ShubhamPalriwala Date: Fri, 25 Aug 2023 17:42:49 +0530 Subject: [PATCH] chore: restructure api docs and rewrite framework-guides --- .../app/docs/api/get-responses/page.mdx | 104 ---- .../app/docs/api/overview/page.mdx | 9 +- .../app/docs/api/survey-response/page.mdx | 320 +++++++++++ .../app/docs/api/webhook/page.mdx | 399 ++++++++++++++ .../attributes/custom-attributes/page.mdx | 2 +- .../docs/client-api/create-response/page.mdx | 116 ---- .../app/docs/client-api/overview/page.mdx | 13 - .../docs/client-api/update-response/page.mdx | 103 ---- .../getting-started/framework-guides/page.mdx | 504 +++++++++--------- .../app/docs/integrations/zapier/page.mdx | 16 +- .../docs/webhook-api/create-webhook/page.mdx | 108 ---- .../docs/webhook-api/delete-webhook/page.mdx | 73 --- .../app/docs/webhook-api/get-webhook/page.mdx | 67 --- .../docs/webhook-api/list-webhooks/page.mdx | 71 --- .../app/docs/webhook-api/overview/page.mdx | 25 - .../docs/webhook-api/webhook-payload/page.mdx | 79 --- .../components/docs/Navigation.tsx | 22 +- 17 files changed, 975 insertions(+), 1056 deletions(-) delete mode 100644 apps/formbricks-com/app/docs/api/get-responses/page.mdx create mode 100644 apps/formbricks-com/app/docs/api/survey-response/page.mdx create mode 100644 apps/formbricks-com/app/docs/api/webhook/page.mdx delete mode 100644 apps/formbricks-com/app/docs/client-api/create-response/page.mdx delete mode 100644 apps/formbricks-com/app/docs/client-api/overview/page.mdx delete mode 100644 apps/formbricks-com/app/docs/client-api/update-response/page.mdx delete mode 100644 apps/formbricks-com/app/docs/webhook-api/create-webhook/page.mdx delete mode 100644 apps/formbricks-com/app/docs/webhook-api/delete-webhook/page.mdx delete mode 100644 apps/formbricks-com/app/docs/webhook-api/get-webhook/page.mdx delete mode 100644 apps/formbricks-com/app/docs/webhook-api/list-webhooks/page.mdx delete mode 100644 apps/formbricks-com/app/docs/webhook-api/overview/page.mdx delete mode 100644 apps/formbricks-com/app/docs/webhook-api/webhook-payload/page.mdx diff --git a/apps/formbricks-com/app/docs/api/get-responses/page.mdx b/apps/formbricks-com/app/docs/api/get-responses/page.mdx deleted file mode 100644 index a462b39040..0000000000 --- a/apps/formbricks-com/app/docs/api/get-responses/page.mdx +++ /dev/null @@ -1,104 +0,0 @@ -export const meta = { - title: "API: Get Responses", - description: "Fetch all the responses for your environment.", -}; - -[API]() - -# API: Get Responses - -## List all Responses {{ tag: 'GET', label: '/api/v1/responses' }} - - - - - Retrieve all the responses you have received for all your surveys. - - ### Mandatory Headers - - - - Your Formbricks API key. - - - - ### Optional Query Params - - - SurveyId to filter responses by. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl --location \ - 'https://app.formbricks.com/api/v1/responses' \ - --header \ - 'x-api-key: ' - ``` - - - - - - ```json {{title:'200 Success'}} - { - "data":[ - { - "id":"cllnfybxd051rpl0gieavthr9", - "createdAt":"2023-08-23T07:56:33.121Z", - "updatedAt":"2023-08-23T07:56:41.793Z", - "surveyId":"cllnfy2780fromy0hy7uoxvtn", - "finished":true, - "data":{ - "ec7agikkr58j8uonhioinkyk":"Loved it!", - "gml6mgy71efgtq8np3s9je5p":"clicked", - "klvpwd4x08x8quesihvw5l92":"Product Manager", - "kp62fbqe8cfzmvy8qwpr81b2":"Very disappointed", - "lkjaxb73ulydzeumhd51sx9g":"Not interesed.", - "ryo75306flyg72iaeditbv51":"Would love if it had dark theme." - }, - "meta":{ - "url":"https://app.formbricks.com/s/cllnfy2780fromy0hy7uoxvtn", - "userAgent":{ - "os":"Linux", - "browser":"Chrome" - } - }, - "personAttributes":null, - "person":null, - "notes":[], - "tags":[] - } - ] - } - ``` - - ```json {{ title: '404 Not Found' }} - { - "code": "not_found", - "message": "cllnfy2780fromy0hy7uoxvt not found", - "details": { - "resource_id": "survey", - "resource_type": "cllnfy2780fromy0hy7uoxvt" - } - } - ``` - - ```json {{ title: '401 Not Authenticated' }} - { - "code": "not_authenticated", - "message": "Not authenticated", - "details": { - "x-Api-Key": "Header not provided or API Key invalid" - } - } - ``` - - - - diff --git a/apps/formbricks-com/app/docs/api/overview/page.mdx b/apps/formbricks-com/app/docs/api/overview/page.mdx index 2aad095ddb..a71af5b388 100644 --- a/apps/formbricks-com/app/docs/api/overview/page.mdx +++ b/apps/formbricks-com/app/docs/api/overview/page.mdx @@ -8,7 +8,7 @@ export const meta = { # API Overview -Formbricks offers two types of APIs: the Public Client API and the User API. Each API serves a different purpose, has different authentication requirements, and provides access to different data and settings. +Formbricks offers two types of APIs: the **Public Client API** and the **User API**. Each API serves a different purpose, has different authentication requirements, and provides access to different data and settings. ## Public Client API @@ -24,4 +24,9 @@ API requests made to the User API are authorized using a personal API key. This To generate, store, or delete an API key, follow the instructions provided on the following page [API Key](/docs/api/api-key-setup). -By understanding the differences between these two APIs, you can choose the appropriate one for your needs, ensuring a secure and efficient integration with the Formbricks platform. + + By understanding the differences between these two APIs, you can choose the appropriate one for your needs, + ensuring a secure and efficient integration with the Formbricks platform. + + +--- diff --git a/apps/formbricks-com/app/docs/api/survey-response/page.mdx b/apps/formbricks-com/app/docs/api/survey-response/page.mdx new file mode 100644 index 0000000000..d79e99e50a --- /dev/null +++ b/apps/formbricks-com/app/docs/api/survey-response/page.mdx @@ -0,0 +1,320 @@ +import { Fence } from "@/components/shared/Fence"; + +export const meta = { + title: "Client API Overview", + description: + "Explore the Formbricks Public Client API for client-side tasks and integration into your website.", +}; + +[Client API]() + +# Client API Overview + +The Public Client API is designed for the JavaScript SDK and does not require authentication. It's primarily used for creating persons, sessions, and responses within the Formbricks platform. This API is ideal for client-side interactions, as it doesn't expose sensitive information. + +--- + +## List all responses {{ tag: 'GET', label: '/api/v1/responses' }} + + + + + Retrieve all the responses you have received for all your surveys. + + ### Mandatory Headers + + + + Your Formbricks API key. + + + + ### Optional Query Params + + + SurveyId to filter responses by. + + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location \ + 'https://app.formbricks.com/api/v1/responses' \ + --header \ + 'x-api-key: ' + ``` + + + + + + ```json {{title:'200 Success'}} + { + "data":[ + { + "id":"cllnfybxd051rpl0gieavthr9", + "createdAt":"2023-08-23T07:56:33.121Z", + "updatedAt":"2023-08-23T07:56:41.793Z", + "surveyId":"cllnfy2780fromy0hy7uoxvtn", + "finished":true, + "data":{ + "ec7agikkr58j8uonhioinkyk":"Loved it!", + "gml6mgy71efgtq8np3s9je5p":"clicked", + "klvpwd4x08x8quesihvw5l92":"Product Manager", + "kp62fbqe8cfzmvy8qwpr81b2":"Very disappointed", + "lkjaxb73ulydzeumhd51sx9g":"Not interesed.", + "ryo75306flyg72iaeditbv51":"Would love if it had dark theme." + }, + "meta":{ + "url":"https://app.formbricks.com/s/cllnfy2780fromy0hy7uoxvtn", + "userAgent":{ + "os":"Linux", + "browser":"Chrome" + } + }, + "personAttributes":null, + "person":null, + "notes":[], + "tags":[] + } + ] + } + ``` + + ```json {{ title: '404 Not Found' }} + { + "code": "not_found", + "message": "cllnfy2780fromy0hy7uoxvt not found", + "details": { + "resource_id": "survey", + "resource_type": "cllnfy2780fromy0hy7uoxvt" + } + } + ``` + + ```json {{ title: '401 Not Authenticated' }} + { + "code": "not_authenticated", + "message": "Not authenticated", + "details": { + "x-Api-Key": "Header not provided or API Key invalid" + } + } + ``` + + + + + +--- + +## Create a response {{ tag: 'POST', label: '/api/v1/client/responses' }} + +Add a new response to a survey. + + + + + ### Mandatory Body Fields + + + + The id of the survey the response belongs to. + + + Marks whether the response is complete or not. + + + The data of the response as JSON object (key: questionId, value: answer). + + + + + ### Optional Body Fields + + + + Internal Formbricks id to identify the user sending the response + + + +### Parameters Explained + +| field name | required | default | description | +| ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| data | yes | - | The response data object (answers to the survey). In this object the key is the questionId, the value the answer of the user to this question. | +| personId | no | - | The person this response is connected to. | +| surveyId | yes | - | The survey this response is connected to. | +| finished | yes | false | Mark a response as complete to be able to filter accordingly. | + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST 'https://app.formbricks.com/api/v1/client/responses' \ + --data-raw '{ + "surveyId":"clfqz1esd0000yzah51trddn8", + "personId": "clfqjny0v000ayzgsycx54a2c", + "finished": true, + "data": { + "clfqjny0v0003yzgscnog1j9i": 10, + "clfqjtn8n0070yzgs6jgx9rog": "I love Formbricks" + } + }' + ``` + + ```json {{ title: 'Example Request Body' }} + { + "personId": "clfqjny0v000ayzgsycx54a2c", + "surveyId": "clfqz1esd0000yzah51trddn8", + "finished": true, + "data": { + "clfqjny0v0003yzgscnog1j9i": 10, + "clfqjtn8n0070yzgs6jgx9rog": "I love Formbricks" + } + } + ``` + + + + + + ```json {{ title: '200 Success' }} + { + "data": { + "id": "clisyqeoi000219t52m5gopke", + "surveyId": "clfqz1esd0000yzah51trddn8", + "finished": true, + "person": { + "id": "clfqjny0v000ayzgsycx54a2c", + "attributes": { + "email": "me@johndoe.com" + } + }, + "data": { + "clfqjny0v0003yzgscnog1j9i": 10, + "clfqjtn8n0070yzgs6jgx9rog": "I love Formbricks" + } + } + } + ``` + + ```json {{ title: '400 Bad Request' }} + { + "code": "bad_request", + "message": "surveyId was not provided.", + "details": { + "surveyId": "This field is required." + } + } + ``` + + + + + + +--- + +## Update a response {{ tag: 'POST', label: '/api/v1/client/responses/[responseId]' }} + +Update an existing response in a survey. + + + + + ### Mandatory Body Fields + + + + The data of the response as JSON object (key: questionId, value: answer). + + + +### Parameters Explained + +| field name | required | default | description | +| ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| data | yes | - | The response data object (answers to the survey). In this object the key is the questionId, the value the answer of the user to this question. | +| finished | yes | false | Mark a response as complete to be able to filter accordingly. | + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST 'https://app.formbricks.com/api/v1/client/responses/[responseId]' \ + --data-raw '{ + "personId": "clfqjny0v000ayzgsycx54a2c", + "surveyId": "clfqz1esd0000yzah51trddn8", + "finished": true, + "data": { + "clggpvpvu0009n40g8ikawby8": 5, + } + }' + ``` + + ```json {{ title: 'Example Request Body' }} + { + "personId": "clfqjny0v000ayzgsycx54a2c", + "surveyId": "clfqz1esd0000yzah51trddn8", + "finished": true, + "data": { + "clggpvpvu0009n40g8ikawby8": 5, + } + } + ``` + + + + + + ```json {{ title: '200 Success' }} + { + "data": { + "id": "clisyqeoi000219t52m5gopke", + "surveyId": "clfqz1esd0000yzah51trddn8", + "finished": true, + "person": { + "id": "clfqjny0v000ayzgsycx54a2c", + "attributes": { + "email": "me@johndoe.com" + } + }, + "data": { + "clfqjny0v0003yzgscnog1j9i": 10, + "clfqjtn8n0070yzgs6jgx9rog": "I love Formbricks", + "clggpvpvu0009n40g8ikawby8": 5 + } + } + } + ``` + + ```json {{ title: '400 Bad Request' }} + { + "code": "bad_request", + "message": "data was not provided.", + "details": { + "data": "This field is required." + } + } + ``` + + ```json {{ title: '404 Not Found' }} + { + "code": "not_found", + "message": "Response not found" + } + ``` + + + + + diff --git a/apps/formbricks-com/app/docs/api/webhook/page.mdx b/apps/formbricks-com/app/docs/api/webhook/page.mdx new file mode 100644 index 0000000000..31d17c6c61 --- /dev/null +++ b/apps/formbricks-com/app/docs/api/webhook/page.mdx @@ -0,0 +1,399 @@ +export const meta = { + title: "Webhook API Overview", + description: "Learn how to use the Formbricks Webhook API.", +}; + +[Webhook API]() + +# Webhook API Overview + +Formbricks' Webhook API offers a powerful interface for interacting with webhooks. Webhooks in Formbricks allow you to receive real-time HTTP notifications of changes to specific objects in the Formbricks environment. + +Before you start managing webhooks, you need to create an API key. This will be used for authorization when making requests to the Webhook API. Please see the [API key setup page](/docs/api/api-key-setup) for more details on how to create and manage your API keys. + +The behavior of the webhooks is determined by their trigger settings. The trigger determines which updates the webhook sends. Current available triggers include "responseCreated", "responseUpdated", and "responseFinished". This allows you to customize your webhooks to only send notifications for the events that are relevant to your application. + +Webhooks are tied to a specific Formbricks environment. Once set, a webhook will receive updates from all surveys within this environment. This makes it easy to manage your data flow and ensure that all relevant updates are caught by the webhook. + +Our API has several REST endpoints enabling you to manage these webhooks, providing a great deal of flexibility: + +1. **List Webhooks:** Retrieve a list of all existing webhooks. +1. **Retrieve Webhook by ID:** Retrieve a specific webhook by it's ID. +1. **Create a New Webhook:** Add a new webhook to your system. +1. **Get a Specific Webhook:** Query the details of a specific webhook using its unique ID. +1. **Delete a Webhook:** Remove an existing webhook. + +These APIs are designed to facilitate seamless integration of Formbricks with third-party systems. By making use of our webhook API, you can automate the process of sending data to these systems whenever significant events occur within your Formbricks environment. + +--- + +## List Webhooks {{ tag: 'GET', label: '/api/v1/webhooks' }} + + + + + Learn how to retrieve a list of all webhooks via API. + + ### Mandatory Headers + + + + Your Formbricks API key. + + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location \ + 'https://app.formbricks.com/api/v1/webhooks' \ + --header \ + 'x-api-key: ' + ``` + + + + + + ```json {{ title: '200 Success' }} + { + "data": [ + { + "id": "cliu1kdza000219zftad4ip6c", + "createdAt": "2023-06-13T08:49:04.198Z", + "updatedAt": "2023-06-13T08:49:04.198Z", + "url": "https://mysystem.com/myendpoint", + "environmentId": "clisypjy4000319t4imm289uo", + "triggers": [ + "responseFinished" + ] + } + ] + } + ``` + + ```json {{ title: '401 Not Authenticated' }} + { + "code": "not_authenticated", + "message": "Not authenticated", + "details": { + "x-Api-Key": "Header not provided or API Key invalid" + } + } + ``` + + + + + + +--- + +## Retrieve Webhook by ID {{ tag: 'GET', label: '/api/v1/webhooks/[webhookId]' }} + + + + + ### Mandatory Headers + + + + Your Formbricks API key. + + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location \ + 'https://app.formbricks.com/api/v1/webhooks/[webhookId]' \ + --header \ + 'x-api-key: ' + ``` + + + + + + ```json {{ title: '200 Success' }} + { + "data": { + "id": "cliu167rk000019zfhbo68bar", + "createdAt": "2023-06-13T08:38:02.960Z", + "updatedAt": "2023-06-13T08:38:02.960Z", + "url": "https://mysystem.com/myendpoint", + "environmentId": "clisypjy4000319t4imm289uo", + "triggers": [ + "responseFinished" + ] + } + } + ``` + + ```json {{ title: '401 Not Authenticated' }} + { + "code": "not_authenticated", + "message": "Not authenticated", + "details": { + "x-Api-Key": "Header not provided or API Key invalid" + } + } + ``` + + + + + + +--- + +## Create Webhook {{ tag: 'POST', label: '/api/v1/webhooks' }} + +Add a webhook to your product. + + + + + ### Mandatory Headers + + + + Your Formbricks API key. + + + + ### Request Body Parameters + + + + The URL where the webhook will send data to. + + + List of events that will trigger the webhook. + + + List of survey IDs that will trigger the webhook. If not provided, the webhook will be triggered for all surveys. + + + +| field name | required | default | description | +| ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------- | +| url | yes | - | The endpoint that the webhook will send data to | +| trigger | yes | - | The event that will trigger the webhook ("responseCreated" or "responseUpdated" or "responseFinished") | +| surveyIds | no | - | List of survey IDs that will trigger the webhook. If not provided, the webhook will be triggered for all surveys. | + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST 'https://app.formbricks.com/api/v1/webhooks' \ + --header 'x-api-key: ' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "url": "https://mysystem.com/myendpoint", + "triggers": ["responseFinished"] + }' + ``` + + ```json {{ title: 'Example Request Body' }} + { + "url": "https://mysystem.com/myendpoint", + "triggers": ["responseFinished"] + } + ``` + + + + + + ```json {{ title: '200 Success' }} + { + "data": { + "id": "cliu1kdza000219zftad4ip6c", + "createdAt": "2023-06-13T08:49:04.198Z", + "updatedAt": "2023-06-13T08:49:04.198Z", + "url": "https://mysystem.com/myendpoint", + "environmentId": "clisypjy4000319t4imm289uo", + "triggers": ["responseFinished"], + "surveyIds": ["clisypjy4000319t4imm289uo"] + } + } + ``` + + ```json {{ title: '400 Bad Request' }} + { + "code": "bad_request", + "message": "Missing trigger", + "details": { + "missing_field": "trigger" + } + } + ``` + + ```json {{ title: '401 Not Authenticated' }} + { + "code": "not_authenticated", + "message": "Not authenticated", + "details": { + "x-Api-Key": "Header not provided or API Key invalid" + } + } + ``` + + + + + + +--- + +## Delete Webhook by ID {{ tag: 'DELETE', label: '/api/v1/webhooks/[webhookId]' }} + + + + + ### Mandatory Headers + + + + Your Formbricks API key. + + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request DELETE 'https://app.formbricks.com/api/v1/webhooks/[webhookId]' \ + --header 'x-api-key: ' + ``` + + + + + + ```json {{ title: '200 Success' }} + { + "data": { + "id": "cliu167rk000019zfhbo68bar", + "createdAt": "2023-06-13T08:38:02.960Z", + "updatedAt": "2023-06-13T08:38:02.960Z", + "url": "https://mysystem.com/myendpoint", + "environmentId": "clisypjy4000319t4imm289uo", + "triggers": ["responseFinished"] + } + } + ``` + + ```json {{ title: '401 Not Authenticated' }} + { + "code": "not_authenticated", + "message": "Not authenticated", + "details": { + "x-Api-Key": "Header not provided or API Key invalid" + } + } + ``` + + ```json {{ title: '404 Not Found' }} + { + "code": "not_found", + "message": "Webhook not found.", + "details": { + "webhookId": "The requested webhook does not exist." + } + } + ``` + + + + + + +--- + +## Webhook Payload + +This documentation helps understand the payload structure that will be received when the webhook is triggered in Formbricks. + + + + +| Variable | Type | Description | +| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| webhookId | String | Webhook's Id | +| event | String | The name of the trigger event [responseCreated, responseUpdated, responseFinished] | +| data | Object | Contains the details of the newly created response. | +| data.id | String | Formbricks Response ID. | +| data.createdAt | String | The timestamp when the response was created. | +| data.updatedAt | String | The timestamp when the response was last updated. | +| data.surveyId | String | The identifier of the survey associated with this response. | +| data.finished | Boolean | A boolean value indicating whether the survey response is marked as finished. | +| data.data | Object | An object containing the response data, where keys are question identifiers, and values are the corresponding answers given by the respondent. | +| data.meta | Object | Additional metadata related to the response, such as the user's operating system and browser information. | +| data.personAttributes | Object | An object with attributes related to the respondent, such as their email and a user ID (if available). | +| data.person | Object | Information about the respondent, including their unique id, attributes, and creation/update timestamps. | +| data.notes | Array | An array of notes associated with the response (if any). | +| data.tags | Array | An array of tags assigned to the response (if any). | + + + + + ### An example webhook payload + + + + ```json + { + "webhookId": "cljwxvjos0003qhnvj2jg4k5i", + "event": "responseCreated", + "data": { + "id": "cljwy2m8r0001qhclco1godnu", + "createdAt": "2023-07-10T14:14:17.115Z", + "updatedAt": "2023-07-10T14:14:17.115Z", + "surveyId": "cljsf3d7a000019cv9apt2t27", + "finished": false, + "data": { + "qumbk3fkr6cky8850bvvq5z1": "Executive" + }, + "meta": { + "userAgent": { + "os": "Mac OS", + "browser": "Chrome" + } + }, + "personAttributes": { + "email": "test@web.com", + "userId": "THIS-IS-A-VERY-LONG-USER-ID-FOR-TESTING" + }, + "person": { + "id": "cljold01t0000qh8ewzigzmjk", + "attributes": { + "email": "test@web.com", + "userId": "THIS-IS-A-VERY-LONG-USER-ID-FOR-TESTING" + }, + "createdAt": "2023-07-04T17:56:17.154Z", + "updatedAt": "2023-07-04T17:56:17.154Z" + }, + "notes": [], + "tags": [] + } + } + ``` + + + + + + +--- diff --git a/apps/formbricks-com/app/docs/attributes/custom-attributes/page.mdx b/apps/formbricks-com/app/docs/attributes/custom-attributes/page.mdx index 0a71f4cf45..91d76f7de0 100644 --- a/apps/formbricks-com/app/docs/attributes/custom-attributes/page.mdx +++ b/apps/formbricks-com/app/docs/attributes/custom-attributes/page.mdx @@ -10,7 +10,7 @@ export const meta = { One way to send attributes to Formbricks is in your code. In Formbricks, there are two special attributes for [user identification](/docs/attributes/identify-users)(user ID & email) and custom attributes. An example: -### Setting Custom User Attributes +## Setting Custom User Attributes You can use the setAttribute function to set any custom attribute for the user (e.g. name, plan, etc.): diff --git a/apps/formbricks-com/app/docs/client-api/create-response/page.mdx b/apps/formbricks-com/app/docs/client-api/create-response/page.mdx deleted file mode 100644 index f9bab88466..0000000000 --- a/apps/formbricks-com/app/docs/client-api/create-response/page.mdx +++ /dev/null @@ -1,116 +0,0 @@ -export const meta = { - title: "API: Create response", - description: "Learn how to create a new response to a survey via API.", -}; - -[Client API]() - -# API: Create Response - -## Create a response {{ tag: 'POST', label: '/api/v1/client/responses' }} - -Add a new response to a survey. - - - - - ### Mandatory Body Fields - - - - The id of the survey the response belongs to. - - - Marks whether the response is complete or not. - - - The data of the response as JSON object (key: questionId, value: answer). - - - - - ### Optional Body Fields - - - - Internal Formbricks id to identify the user sending the response - - - -### Parameters Explained - -| field name | required | default | description | -| ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| data | yes | - | The response data object (answers to the survey). In this object the key is the questionId, the value the answer of the user to this question. | -| personId | no | - | The person this response is connected to. | -| surveyId | yes | - | The survey this response is connected to. | -| finished | yes | false | Mark a response as complete to be able to filter accordingly. | - - - - - - - ```bash {{ title: 'cURL' }} - curl --location --request POST 'https://app.formbricks.com/api/v1/client/responses' \ - --data-raw '{ - "surveyId":"clfqz1esd0000yzah51trddn8", - "personId": "clfqjny0v000ayzgsycx54a2c", - "finished": true, - "data": { - "clfqjny0v0003yzgscnog1j9i": 10, - "clfqjtn8n0070yzgs6jgx9rog": "I love Formbricks" - } - }' - ``` - - ```json {{ title: 'Example Request Body' }} - { - "personId": "clfqjny0v000ayzgsycx54a2c", - "surveyId": "clfqz1esd0000yzah51trddn8", - "finished": true, - "data": { - "clfqjny0v0003yzgscnog1j9i": 10, - "clfqjtn8n0070yzgs6jgx9rog": "I love Formbricks" - } - } - ``` - - - - - - ```json {{ title: '200 Success' }} - { - "data": { - "id": "clisyqeoi000219t52m5gopke", - "surveyId": "clfqz1esd0000yzah51trddn8", - "finished": true, - "person": { - "id": "clfqjny0v000ayzgsycx54a2c", - "attributes": { - "email": "me@johndoe.com" - } - }, - "data": { - "clfqjny0v0003yzgscnog1j9i": 10, - "clfqjtn8n0070yzgs6jgx9rog": "I love Formbricks" - } - } - } - ``` - - ```json {{ title: '400 Bad Request' }} - { - "code": "bad_request", - "message": "surveyId was not provided.", - "details": { - "surveyId": "This field is required." - } - } - ``` - - - - - diff --git a/apps/formbricks-com/app/docs/client-api/overview/page.mdx b/apps/formbricks-com/app/docs/client-api/overview/page.mdx deleted file mode 100644 index b065a4dd99..0000000000 --- a/apps/formbricks-com/app/docs/client-api/overview/page.mdx +++ /dev/null @@ -1,13 +0,0 @@ -import { Fence } from "@/components/shared/Fence"; - -export const meta = { - title: "Client API Overview", - description: - "Explore the Formbricks Public Client API for client-side tasks and integration into your website.", -}; - -[Client API]() - -# Client API Overview - -The Public Client API is designed for the JavaScript SDK and does not require authentication. It's primarily used for creating persons, sessions, and responses within the Formbricks platform. This API is ideal for client-side interactions, as it doesn't expose sensitive information. diff --git a/apps/formbricks-com/app/docs/client-api/update-response/page.mdx b/apps/formbricks-com/app/docs/client-api/update-response/page.mdx deleted file mode 100644 index cad8d5ccac..0000000000 --- a/apps/formbricks-com/app/docs/client-api/update-response/page.mdx +++ /dev/null @@ -1,103 +0,0 @@ -export const meta = { - title: "API: Update submission", - description: "Learn how to update a new response to a survey via API.", -}; - -[Client API]() - -# API: Update Response - -Update an existing response in a survey. - - - - - ### Mandatory Body Fields - - - - The data of the response as JSON object (key: questionId, value: answer). - - - -### Parameters Explained - -| field name | required | default | description | -| ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| data | yes | - | The response data object (answers to the survey). In this object the key is the questionId, the value the answer of the user to this question. | -| finished | yes | false | Mark a response as complete to be able to filter accordingly. | - - - - - - - ```bash {{ title: 'cURL' }} - curl --location --request POST 'https://app.formbricks.com/api/v1/client/responses/[responseId]' \ - --data-raw '{ - "personId": "clfqjny0v000ayzgsycx54a2c", - "surveyId": "clfqz1esd0000yzah51trddn8", - "finished": true, - "data": { - "clggpvpvu0009n40g8ikawby8": 5, - } - }' - ``` - - ```json {{ title: 'Example Request Body' }} - { - "personId": "clfqjny0v000ayzgsycx54a2c", - "surveyId": "clfqz1esd0000yzah51trddn8", - "finished": true, - "data": { - "clggpvpvu0009n40g8ikawby8": 5, - } - } - ``` - - - - - - ```json {{ title: '200 Success' }} - { - "data": { - "id": "clisyqeoi000219t52m5gopke", - "surveyId": "clfqz1esd0000yzah51trddn8", - "finished": true, - "person": { - "id": "clfqjny0v000ayzgsycx54a2c", - "attributes": { - "email": "me@johndoe.com" - } - }, - "data": { - "clfqjny0v0003yzgscnog1j9i": 10, - "clfqjtn8n0070yzgs6jgx9rog": "I love Formbricks", - "clggpvpvu0009n40g8ikawby8": 5 - } - } - } - ``` - - ```json {{ title: '400 Bad Request' }} - { - "code": "bad_request", - "message": "data was not provided.", - "details": { - "data": "This field is required." - } - } - ``` - - ```json {{ title: '404 Not Found' }} - { - "code": "not_found", - "message": "Response not found" - } - ``` - - - - - diff --git a/apps/formbricks-com/app/docs/getting-started/framework-guides/page.mdx b/apps/formbricks-com/app/docs/getting-started/framework-guides/page.mdx index 370f94cf0e..c335192257 100644 --- a/apps/formbricks-com/app/docs/getting-started/framework-guides/page.mdx +++ b/apps/formbricks-com/app/docs/getting-started/framework-guides/page.mdx @@ -33,337 +33,310 @@ Before getting started, make sure you have: ## Formbricks x HTML - - - All you need to do is copy a ` +``` + - - - Formbricks Environment ID.
- _Get this from the Setup Checklist inside the Settings page of Formbricks dashboard_ - - - - - URL of the hosted Formbricks instance.
- _If you're using the cloud app, please use `"https://app.formbricks.com`"_ - - +### Required Customizations to be Made - Now visit the [Validate your Setup](#validate-your-setup) section to verify your setup! + + + Formbricks Environment ID. + + + + + URL of the hosted Formbricks instance. + + - - - - ```html {{ title: '.html' }} - - ``` - - - +Now visit the [Validate your Setup](#validate-your-setup) section to verify your setup! ## Formbricks x ReactJS - - - - Install the Formbricks SDK using one of the package managers ie `npm`,`pnpm`,`yarn`.
- Now, update your App.js/ts file to initialise Formbricks. +Install the Formbricks SDK using one of the package managers ie `npm`,`pnpm`,`yarn`. - ### Required Customizations to be Made + +```sh {{ title: 'npm' }} +npm install --save @formbricks/js +``` +```sh {{ title: 'pnpm' }} +pnpm add @formbricks/js +``` +```sh {{ title: 'yarn' }} +yarn add @formbricks/js +``` + - - - Formbricks Environment ID.
- _Get this from the Setup Checklist inside the Settings page of Formbricks dashboard_ - - - - - URL of the hosted Formbricks instance.
- _If you're using the cloud app, please use `"https://app.formbricks.com`"_ - - +Now, update your App.js/ts file to initialise Formbricks. - ### What are we doing here? + - The app initializes 'formbricks' when it's loaded in a browser environment (due to the typeof window !== "undefined" check) and then renders your components or content. +```js - In app survey in React app for micro surveys +// other imports +import formbricks from "@formbricks/js"; - Now visit the [Validate your Setup](#validate-your-setup) section to verify your setup! +if (typeof window !== "undefined") { + formbricks.init({ + environmentId: "", + apiHost: "", + debug: true, // remove when in production + }); +} - - - - ```sh {{ title: 'npm' }} - npm install --save @formbricks/js - ``` - ```sh {{ title: 'pnpm' }} - pnpm add @formbricks/js - ``` - ```sh {{ title: 'yarn' }} - yarn add @formbricks/js - ``` - - - ```js {{ title: 'app.js' }} - // other imports - import formbricks from "@formbricks/js"; +function App() { + // your own app +} - if (typeof window !== "undefined") { - formbricks.init({ - environmentId: "", - apiHost: "", - debug: true, // remove when in production - }); - } +export default App; +``` - function App() { - // your own app - } + - export default App; - ``` - +### Required Customizations to be Made - - + + + Formbricks Environment ID. + + + + + URL of the hosted Formbricks instance. + + + +### What are we doing here? + +The app initializes 'formbricks' when it's loaded in a browser environment (due to the typeof window !== "undefined" check) and then renders your components or content. + +In app survey in React app for micro surveys + +Now visit the [Validate your Setup](#validate-your-setup) section to verify your setup! ## Formbricks x NextJS - - +NextJs projects typically follow two main conventions: the App Directory and the Pages Directory. +To ensure smooth integration with the Formbricks SDK, which operates solely on the client side, follow the +guidelines for each convention below: - NextJs projects typically follow two main conventions: the App Directory and the Pages Directory. - To ensure smooth integration with the Formbricks SDK, which operates solely on the client side, follow the - guidelines for each convention below: +- App directory: You will have to define a new component in `app/formbricks.tsx` file and call it in your `app/layout.tsx` file. +- Pages directory: You will have to visit your `_app.tsx` and just initialise Formbricks there. - - App directory: You will have to define a new component in `app/formbricks.tsx` file and call it in your `app/layout.tsx` file. - - Pages directory: You will have to visit your `_app.tsx` and just initialise Formbricks there. +Code snippets for the integration for both conventions are provided to further assist you. - Code snippets for the integration for both conventions are provided to further assist you. + +```shell {{ title: 'npm' }} +npm install --save @formbricks/js +``` +```shell {{ title: 'pnpm' }} +pnpm add @formbricks/js +``` +```shell {{ title: 'yarn' }} +yarn add @formbricks/js +``` + - ### Required Customizations to be Made +### App Directory - - - Formbricks Environment ID.
- _Get this from the Setup Checklist inside the Settings page of Formbricks dashboard_ - - - - - URL of the hosted Formbricks instance.
- _If you're using the cloud app, please use `"https://app.formbricks.com`"_ - - + +```tsx {{title: 'Typescript'}} +"use client"; +import formbricks from "@formbricks/js"; +import { usePathname, useSearchParams } from "next/navigation"; +import { useEffect } from "react"; - ### Optional Customizations to be Made +export default function FormbricksProvider() { +const pathname = usePathname(); +const searchParams = useSearchParams(); - - - Whether you want to see debug messages from Formbricks on your client-side console. - - +useEffect(() => { + formbricks.init({ + environmentId: "", + apiHost: "", + debug: true, // remove when in production + }); +}, []); - ### What are we doing here? +useEffect(() => { + formbricks?.registerRouteChange(); +}, [pathname, searchParams]); - First we need to initialize the Formbricks SDK, making sure it only runs on the client side. - To connect the Next.js router to Formbricks and ensure the SDK can keep track of every page change, we are registering the route change event. +return null; +} +``` + - Now visit the [Validate your Setup](#validate-your-setup) section to verify your setup! + +```tsx {{title: 'Typescript'}} +import FormbricksProvider from "./formbricks"; +import "./globals.css"; - - - - ```shell {{ title: 'npm' }} - npm install --save @formbricks/js - ``` - ```shell {{ title: 'pnpm' }} - pnpm add @formbricks/js - ``` - ```shell {{ title: 'yarn' }} - yarn add @formbricks/js - ``` +export default function RootLayout({ children }: { children: React.ReactNode }) { +return ( + + + {children} + +); +} +``` - - - ```tsx {{ title: 'app/formbricks.tsx' }} - "use client"; - import formbricks from "@formbricks/js"; - import { usePathname, useSearchParams } from "next/navigation"; - import { useEffect } from "react"; + - export default function FormbricksProvider() { - const pathname = usePathname(); - const searchParams = useSearchParams(); +### Pages Directory - useEffect(() => { - formbricks.init({ - environmentId: "", - apiHost: "", - debug: true, // remove when in production - }); - }, []); + +```tsx {{ title: 'Typescript' }} +import "@/styles/globals.css"; +import type { PagesProps } from "next/app"; +import { useEffect } from "react"; +import { useRouter } from "next/router"; +import formbricks from "@formbricks/js"; - useEffect(() => { - formbricks?.registerRouteChange(); - }, [pathname, searchParams]); +if (typeof window !== "undefined") { +formbricks.init({ + environmentId: "your-environment-id", + apiHost: "your-api-host", // e.g. https://app.formbricks.com + debug: true, // remove when in production +}); +} - return null; - } - ``` +export default function Pages({ Component, pageProps }: PagesProps) { +const router = useRouter(); - ```js {{ title: 'app/layout.tsx' }} - import FormbricksProvider from "./formbricks"; - import "./globals.css"; +useEffect(() => { + // Connect next.js router to Formbricks + const handleRouteChange = formbricks?.registerRouteChange; + router.events.on("routeChangeComplete", handleRouteChange); - export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - {children} - - ); - } - ``` + return () => { + router.events.off("routeChangeComplete", handleRouteChange); + }; +}, []); - +return ; +} +``` + - - ```tsx {{ title: '_app.tsx' }} - import "@/styles/globals.css"; - import type { PagesProps } from "next/app"; - import { useEffect } from "react"; - import { useRouter } from "next/router"; - import formbricks from "@formbricks/js"; +### Required Customizations to be Made - if (typeof window !== "undefined") { - formbricks.init({ - environmentId: "your-environment-id", - apiHost: "your-api-host", // e.g. https://app.formbricks.com - debug: true, // remove when in production - }); - } + + + Formbricks Environment ID. + + + + + URL of the hosted Formbricks instance. + + - export default function Pages({ Component, pageProps }: PagesProps) { - const router = useRouter(); +### Optional Customizations to be Made - useEffect(() => { - // Connect next.js router to Formbricks - const handleRouteChange = formbricks?.registerRouteChange; - router.events.on("routeChangeComplete", handleRouteChange); + + + Whether you want to see debug messages from Formbricks on your client-side console. + + - return () => { - router.events.off("routeChangeComplete", handleRouteChange); - }; - }, []); +### What are we doing here? - return ; - } - ``` - +First we need to initialize the Formbricks SDK, making sure it only runs on the client side. +To connect the Next.js router to Formbricks and ensure the SDK can keep track of every page change, we are registering the route change event. - - +Now visit the [Validate your Setup](#validate-your-setup) section to verify your setup! ## Formbricks x VueJs - - +Integrating the Formbricks SDK with Vue.js is a straightforward process. +We will make sure the SDK is only loaded and used on the client side, as it's not intended for server-side usage. - Integrating the Formbricks SDK with Vue.js is a straightforward process. - We will make sure the SDK is only loaded and used on the client side, as it's not intended for server-side usage. + +```shell {{ title: 'npm' }} +npm install --save @formbricks/js +``` +```shell {{ title: 'pnpm' }} +pnpm add @formbricks/js +``` +```shell {{ title: 'yarn' }} +yarn add @formbricks/js +``` - ### Required Customizations to be Made + - - - Formbricks Environment ID.
- _Get this from the Setup Checklist inside the Settings page of Formbricks dashboard_ - - - - - URL of the hosted Formbricks instance.
- _If you're using the cloud app, please use `"https://app.formbricks.com`"_ - - + +```js +import formbricks from "@formbricks/js"; - ### Optional Customizations to be Made +if (typeof window !== "undefined") { + formbricks.init({ + environmentId: "", + apiHost: "", + }); +} - - - Whether you want to see debug messages from Formbricks on your client-side console. - - +export default formbricks; +``` - Now visit the [Validate your Setup](#validate-your-setup) section to verify your setup! +```js {{ title: 'main.js' }} +// other imports +import Vue from "vue"; +import VueRouter from "vue-router"; +import formbricks from "@/formbricks"; - - - - ```shell {{ title: 'npm' }} - npm install --save @formbricks/js - ``` - ```shell {{ title: 'pnpm' }} - pnpm add @formbricks/js - ``` - ```shell {{ title: 'yarn' }} - yarn add @formbricks/js - ``` +Vue.use(VueRouter); - - - ```js {{ title: 'src/formbricks.js' }} - import formbricks from "@formbricks/js"; +const router = new VueRouter({ + // Your router configuration here +}); - if (typeof window !== "undefined") { - formbricks.init({ - environmentId: "", - apiHost: "", - }); - } +// Add a global navigation guard +router.afterEach((to, from) => { + if (typeof formbricks !== "undefined") { + formbricks.registerRouteChange(); + } +}); +``` - export default formbricks; - ``` + - ```js {{ title: 'main.js' }} - // other imports - import Vue from "vue"; - import VueRouter from "vue-router"; - import formbricks from "@/formbricks"; +### Required Customizations to be Made + + + Formbricks Environment ID. + + + + + URL of the hosted Formbricks instance. + + - Vue.use(VueRouter); +### Optional Customizations to be Made - const router = new VueRouter({ - // Your router configuration here - }); + + + Whether you want to see debug messages from Formbricks on your client-side console. + + - // Add a global navigation guard - router.afterEach((to, from) => { - if (typeof formbricks !== "undefined") { - formbricks.registerRouteChange(); - } - }); - ``` - - - - - +Now visit the [Validate your Setup](#validate-your-setup) section to verify your setup! ## Validate your setup @@ -386,4 +359,3 @@ To this: /> **Can’t figure it out? [Join our Discord!](https://formbricks.com/discord)** - diff --git a/apps/formbricks-com/app/docs/integrations/zapier/page.mdx b/apps/formbricks-com/app/docs/integrations/zapier/page.mdx index f91ee05946..17f4b326b9 100644 --- a/apps/formbricks-com/app/docs/integrations/zapier/page.mdx +++ b/apps/formbricks-com/app/docs/integrations/zapier/page.mdx @@ -26,7 +26,7 @@ export const meta = { Zapier is a powerful ally. Hook up Formbricks with Zapier and you can send your data to 5000+ other apps. Here is how to do it. - ## Nail down your survey first? {{ class: "text-white" }} + ### Nail down your survey first? {{ class: "text-white" }} Any changes in the survey cause additional work in the Zap. It makes sense to first settle on the survey you want to run and then get to setting up Zapier. @@ -45,7 +45,7 @@ When setting up the Zap your life will be easier when you change the `questionId _In every question card in the Advanced Settings you find the Question ID field. Update it so that you’ll recognize the response tied to this question._ - ## Already published? Duplicate survey {{ class: "text-white" }} + ### Already published? Duplicate survey {{ class: "text-white" }} You can only update the questionId when the survey was not yet published. Already published it? Just **duplicate it** to update the questionIds. -## Step 3: Send a test response +## Step 2: Send a test response In order to set up Zapier you’ll need a test response. This allows you to select the individual values of each response in your Zap. If you have Formbricks running locally and you want to set up an in-app survey, you can use our [Demo App](/docs/contributing/demo) to trigger a survey and submit a response. @@ -67,7 +67,7 @@ In order to set up Zapier you’ll need a test response. This allows you to sele className="rounded-lg max-w-full sm:max-w-3xl" /> -## Step 4: Setup your Zap +## Step 3: Setup your Zap Go to [zapier.com](https://zapier.com) and create a new Zap. Search for “Formbricks” to get started: @@ -77,7 +77,7 @@ Then, choose the event you want to trigger the Zap on: Choose Event -## Step 5: Connect Formbricks with Zapier +## Step 4: Connect Formbricks with Zapier Now, you have to connect Zapier with Formbricks via an API Key: @@ -105,13 +105,13 @@ Once you copied it in the newly opened Zapier window, you will be connected: className="rounded-lg max-w-full sm:max-w-3xl" /> -## Step 6: Select Survey +## Step 5: Select Survey Next, you can choose from all the surveys you have created in this environment: Select Survey -## Step 7: Test your trigger +## Step 6: Test your trigger Once you hit “Test” you will see the three most recent submissions for this survey. If you don’t have any submissions in the survey, submit one to continue setting up your Zap: @@ -123,7 +123,7 @@ Once you hit “Test” you will see the three most recent submissions for this /> _Now you're happy that you updated the questionId's_ -## Step 8: Set up your Zap +## Step 7: Set up your Zap Now you have all the data you need at hand. The next steps depend on what you want to do with it. In this tutorial, we will send submissions to a Slack channel: diff --git a/apps/formbricks-com/app/docs/webhook-api/create-webhook/page.mdx b/apps/formbricks-com/app/docs/webhook-api/create-webhook/page.mdx deleted file mode 100644 index bbe21b8545..0000000000 --- a/apps/formbricks-com/app/docs/webhook-api/create-webhook/page.mdx +++ /dev/null @@ -1,108 +0,0 @@ -export const meta = { - title: "API: Create webhook", - description: "Learn how to create a new webhook via API.", -}; - -[Webhook API]() - -# API: Create webhook - -## Create a new Webhook {{ tag: 'POST', label: '/api/v1/webhooks' }} - -Add a webhook to your product. - - - - - ### Mandatory Headers - - - - Your Formbricks API key. - - - - ### Request Body Parameters - - - - The URL where the webhook will send data to. - - - List of events that will trigger the webhook. - - - List of survey IDs that will trigger the webhook. If not provided, the webhook will be triggered for all surveys. - - - -| field name | required | default | description | -| ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------- | -| url | yes | - | The endpoint that the webhook will send data to | -| trigger | yes | - | The event that will trigger the webhook ("responseCreated" or "responseUpdated" or "responseFinished") | -| surveyIds | no | - | List of survey IDs that will trigger the webhook. If not provided, the webhook will be triggered for all surveys. | - - - - - - - ```bash {{ title: 'cURL' }} - curl --location --request POST 'https://app.formbricks.com/api/v1/webhooks' \ - --header 'x-api-key: ' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "url": "https://mysystem.com/myendpoint", - "triggers": ["responseFinished"] - }' - ``` - - ```json {{ title: 'Example Request Body' }} - { - "url": "https://mysystem.com/myendpoint", - "triggers": ["responseFinished"] - } - ``` - - - - - - ```json {{ title: '200 Success' }} - { - "data": { - "id": "cliu1kdza000219zftad4ip6c", - "createdAt": "2023-06-13T08:49:04.198Z", - "updatedAt": "2023-06-13T08:49:04.198Z", - "url": "https://mysystem.com/myendpoint", - "environmentId": "clisypjy4000319t4imm289uo", - "triggers": ["responseFinished"], - "surveyIds": ["clisypjy4000319t4imm289uo"] - } - } - ``` - - ```json {{ title: '400 Bad Request' }} - { - "code": "bad_request", - "message": "Missing trigger", - "details": { - "missing_field": "trigger" - } - } - ``` - - ```json {{ title: '401 Not Authenticated' }} - { - "code": "not_authenticated", - "message": "Not authenticated", - "details": { - "x-Api-Key": "Header not provided or API Key invalid" - } - } - ``` - - - - - diff --git a/apps/formbricks-com/app/docs/webhook-api/delete-webhook/page.mdx b/apps/formbricks-com/app/docs/webhook-api/delete-webhook/page.mdx deleted file mode 100644 index 31bfbd46ed..0000000000 --- a/apps/formbricks-com/app/docs/webhook-api/delete-webhook/page.mdx +++ /dev/null @@ -1,73 +0,0 @@ -export const meta = { - title: "API: Delete Webhook", - description: "Learn how to delete a specific webhook by its ID via API.", -}; - -[Webhook API]() - -# API: Delete Webhook - -## Delete a specific webhook by its ID {{ tag: 'DELETE', label: '/api/v1/webhooks/[webhookId]' }} - - - - - ### Mandatory Headers - - - - Your Formbricks API key. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl --location --request DELETE 'https://app.formbricks.com/api/v1/webhooks/[webhookId]' \ - --header 'x-api-key: ' - ``` - - - - - - ```json {{ title: '200 Success' }} - { - "data": { - "id": "cliu167rk000019zfhbo68bar", - "createdAt": "2023-06-13T08:38:02.960Z", - "updatedAt": "2023-06-13T08:38:02.960Z", - "url": "https://mysystem.com/myendpoint", - "environmentId": "clisypjy4000319t4imm289uo", - "triggers": ["responseFinished"] - } - } - ``` - - ```json {{ title: '401 Not Authenticated' }} - { - "code": "not_authenticated", - "message": "Not authenticated", - "details": { - "x-Api-Key": "Header not provided or API Key invalid" - } - } - ``` - - ```json {{ title: '404 Not Found' }} - { - "code": "not_found", - "message": "Webhook not found.", - "details": { - "webhookId": "The requested webhook does not exist." - } - } - ``` - - - - - diff --git a/apps/formbricks-com/app/docs/webhook-api/get-webhook/page.mdx b/apps/formbricks-com/app/docs/webhook-api/get-webhook/page.mdx deleted file mode 100644 index ba8cb13221..0000000000 --- a/apps/formbricks-com/app/docs/webhook-api/get-webhook/page.mdx +++ /dev/null @@ -1,67 +0,0 @@ -export const meta = { - title: "API: Get Webhook", - description: "Learn how to retrieve a specific webhook by its ID via API.", -}; - -[Webhook API]() - -# API: Get Webhook - -## Retrieve a specific webhook by its ID {{ tag: 'GET', label: '/api/v1/webhooks/[webhookId]' }} - - - - - ### Mandatory Headers - - - - Your Formbricks API key. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl --location \ - 'https://app.formbricks.com/api/v1/webhooks/[webhookId]' \ - --header \ - 'x-api-key: ' - ``` - - - - - - ```json {{ title: '200 Success' }} - { - "data": { - "id": "cliu167rk000019zfhbo68bar", - "createdAt": "2023-06-13T08:38:02.960Z", - "updatedAt": "2023-06-13T08:38:02.960Z", - "url": "https://mysystem.com/myendpoint", - "environmentId": "clisypjy4000319t4imm289uo", - "triggers": [ - "responseFinished" - ] - } - } - ``` - - ```json {{ title: '401 Not Authenticated' }} - { - "code": "not_authenticated", - "message": "Not authenticated", - "details": { - "x-Api-Key": "Header not provided or API Key invalid" - } - } - ``` - - - - - diff --git a/apps/formbricks-com/app/docs/webhook-api/list-webhooks/page.mdx b/apps/formbricks-com/app/docs/webhook-api/list-webhooks/page.mdx deleted file mode 100644 index d737b8b6d3..0000000000 --- a/apps/formbricks-com/app/docs/webhook-api/list-webhooks/page.mdx +++ /dev/null @@ -1,71 +0,0 @@ -export const meta = { - title: "API: List Webhooks", - description: "Learn how to retrieve a list of all webhooks via API.", -}; - -[Webhook API]() - -# API: List Webhooks - -## Retrieve a list of all webhooks {{ tag: 'GET', label: '/api/v1/webhooks' }} - - - - - Learn how to retrieve a list of all webhooks via API. - - ### Mandatory Headers - - - - Your Formbricks API key. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl --location \ - 'https://app.formbricks.com/api/v1/webhooks' \ - --header \ - 'x-api-key: ' - ``` - - - - - - ```json {{ title: '200 Success' }} - { - "data": [ - { - "id": "cliu1kdza000219zftad4ip6c", - "createdAt": "2023-06-13T08:49:04.198Z", - "updatedAt": "2023-06-13T08:49:04.198Z", - "url": "https://mysystem.com/myendpoint", - "environmentId": "clisypjy4000319t4imm289uo", - "triggers": [ - "responseFinished" - ] - } - ] - } - ``` - - ```json {{ title: '401 Not Authenticated' }} - { - "code": "not_authenticated", - "message": "Not authenticated", - "details": { - "x-Api-Key": "Header not provided or API Key invalid" - } - } - ``` - - - - - diff --git a/apps/formbricks-com/app/docs/webhook-api/overview/page.mdx b/apps/formbricks-com/app/docs/webhook-api/overview/page.mdx deleted file mode 100644 index 6fecfa222a..0000000000 --- a/apps/formbricks-com/app/docs/webhook-api/overview/page.mdx +++ /dev/null @@ -1,25 +0,0 @@ -export const meta = { - title: "Webhook API Overview", - description: "Learn how to use the Formbricks Webhook API.", -}; - -[Webhook API]() - -# Webhook API Overview - -Formbricks' Webhook API offers a powerful interface for interacting with webhooks. Webhooks in Formbricks allow you to receive real-time HTTP notifications of changes to specific objects in the Formbricks environment. - -Before you start managing webhooks, you need to create an API key. This will be used for authorization when making requests to the Webhook API. Please see the [API key setup page](/docs/api/api-key-setup) for more details on how to create and manage your API keys. - -The behavior of the webhooks is determined by their trigger settings. The trigger determines which updates the webhook sends. Current available triggers include "responseCreated", "responseUpdated", and "responseFinished". This allows you to customize your webhooks to only send notifications for the events that are relevant to your application. - -Webhooks are tied to a specific Formbricks environment. Once set, a webhook will receive updates from all surveys within this environment. This makes it easy to manage your data flow and ensure that all relevant updates are caught by the webhook. - -Our API has several REST endpoints enabling you to manage these webhooks, providing a great deal of flexibility: - -1. **List Webhooks:** Retrieve a list of all existing webhooks. -2. **Create a New Webhook:** Add a new webhook to your system. -3. **Get a Specific Webhook:** Query the details of a specific webhook using its unique ID. -4. **Delete a Webhook:** Remove an existing webhook. - -These APIs are designed to facilitate seamless integration of Formbricks with third-party systems. By making use of our webhook API, you can automate the process of sending data to these systems whenever significant events occur within your Formbricks environment. diff --git a/apps/formbricks-com/app/docs/webhook-api/webhook-payload/page.mdx b/apps/formbricks-com/app/docs/webhook-api/webhook-payload/page.mdx deleted file mode 100644 index fc1474b3d5..0000000000 --- a/apps/formbricks-com/app/docs/webhook-api/webhook-payload/page.mdx +++ /dev/null @@ -1,79 +0,0 @@ -export const meta = { - title: "Webhook Payload", - description: "Learn how to handle the Formbricks API payload.", -}; - -[Webhook API]() - -# Webhook Payload - -This documentation helps understand the payload structure that will be received when the webhook is triggered in Formbricks. - - - - -| Variable | Type | Description | -| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| webhookId | String | Webhook's Id | -| event | String | The name of the trigger event [responseCreated, responseUpdated, responseFinished] | -| data | Object | Contains the details of the newly created response. | -| data.id | String | Formbricks Response ID. | -| data.createdAt | String | The timestamp when the response was created. | -| data.updatedAt | String | The timestamp when the response was last updated. | -| data.surveyId | String | The identifier of the survey associated with this response. | -| data.finished | Boolean | A boolean value indicating whether the survey response is marked as finished. | -| data.data | Object | An object containing the response data, where keys are question identifiers, and values are the corresponding answers given by the respondent. | -| data.meta | Object | Additional metadata related to the response, such as the user's operating system and browser information. | -| data.personAttributes | Object | An object with attributes related to the respondent, such as their email and a user ID (if available). | -| data.person | Object | Information about the respondent, including their unique id, attributes, and creation/update timestamps. | -| data.notes | Array | An array of notes associated with the response (if any). | -| data.tags | Array | An array of tags assigned to the response (if any). | - - - - - ## An example webhook payload - - - - ```json - { - "webhookId": "cljwxvjos0003qhnvj2jg4k5i", - "event": "responseCreated", - "data": { - "id": "cljwy2m8r0001qhclco1godnu", - "createdAt": "2023-07-10T14:14:17.115Z", - "updatedAt": "2023-07-10T14:14:17.115Z", - "surveyId": "cljsf3d7a000019cv9apt2t27", - "finished": false, - "data": { - "qumbk3fkr6cky8850bvvq5z1": "Executive" - }, - "meta": { - "userAgent": { - "os": "Mac OS", - "browser": "Chrome" - } - }, - "personAttributes": { - "email": "test@web.com", - "userId": "THIS-IS-A-VERY-LONG-USER-ID-FOR-TESTING" - }, - "person": { - "id": "cljold01t0000qh8ewzigzmjk", - "attributes": { - "email": "test@web.com", - "userId": "THIS-IS-A-VERY-LONG-USER-ID-FOR-TESTING" - }, - "createdAt": "2023-07-04T17:56:17.154Z", - "updatedAt": "2023-07-04T17:56:17.154Z" - }, - "notes": [], - "tags": [] - } - } - ``` - - - - diff --git a/apps/formbricks-com/components/docs/Navigation.tsx b/apps/formbricks-com/components/docs/Navigation.tsx index 766ab77b0d..342b557ab1 100644 --- a/apps/formbricks-com/components/docs/Navigation.tsx +++ b/apps/formbricks-com/components/docs/Navigation.tsx @@ -239,26 +239,8 @@ export const navigation: Array = [ links: [ { title: "Overview", href: "/docs/api/overview" }, { title: "API Key Setup", href: "/docs/api/api-key-setup" }, - { title: "Get Responses", href: "/docs/api/get-responses" }, - ], - }, - { - title: " Client API", - links: [ - { title: "Overview", href: "/docs/client-api/overview" }, - { title: "Create Response", href: "/docs/client-api/create-response" }, - { title: "Update Response", href: "/docs/client-api/update-response" }, - ], - }, - { - title: "Webhook API", - links: [ - { title: "Overview", href: "/docs/webhook-api/overview" }, - { title: "List Webhooks", href: "/docs/webhook-api/list-webhooks" }, - { title: "Get Webhook", href: "/docs/webhook-api/get-webhook" }, - { title: "Create Webhook", href: "/docs/webhook-api/create-webhook" }, - { title: "Delete Webhook", href: "/docs/webhook-api/delete-webhook" }, - { title: "Webhook Payload", href: "/docs/webhook-api/webhook-payload" }, + { title: "Survey Response", href: "/docs/api/survey-response" }, + { title: "Webhook", href: "/docs/api/webhook" }, ], }, {