Create connector tool

post

https://partner.gupshup.io/partner/app/{appId}/bizai/agent_connectors/{connectorId}/tools

Recent Requests

Log in to see full request history

Time	Status	User Agent
Retrieving recent requests…

Loading…

Request parameters

Parameter	Type	Required	In	Description
`Authorization`	string	Yes	Header	Partner app token, sent raw. `Bearer <token>` is also accepted.
`Content-Type`	string	Yes	Header	`application/json`
`appId`	string (uuid)	Yes	Path	Partner Portal app id. Stands in for Meta's `entity_id`.
`connectorId`	string	Yes	Path	Connector id (pfbid). Meta `pfbid…` id.
`name`	string	Yes	Body	Name.
`description`	string	Yes	Body	Human-readable description.
`request_definition`	object	Yes	Body	The outbound HTTP call the tool makes.
`request_definition.method`	string	Yes	Body	One of: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`.
`request_definition.path`	string	Yes	Body	e.g. `/orders/{order_id}`.
`request_definition.path_parameters`	object	No	Body	Path placeholders, keyed by name.
`request_definition.path_parameters.{key}`	object	No	Body	One entry per name.
`request_definition.path_parameters.{key}.type`	string	Yes	Body	One of: `string`, `integer`, `number`, `boolean`.
`request_definition.path_parameters.{key}.description`	string	No	Body	Human-readable description.
`request_definition.path_parameters.{key}.required`	boolean	No	Body	`true` if the model must supply a value.
`request_definition.path_parameters.{key}.binding`	object	No	Body	Fills a parameter from a fixed value or a runtime macro instead of the model.
`request_definition.path_parameters.{key}.binding.kind`	string	Yes	Body	One of: `default`, `macro`.
`request_definition.path_parameters.{key}.binding.value`	string	No	Body	Fixed value used when `kind` is `default`.
`request_definition.path_parameters.{key}.binding.macro`	string	No	Body	One of: `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`, `WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`, `WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID`, `INSTAGRAM_CONVERSATION_ID`.
`request_definition.query_parameters`	object	No	Body	Query parameters, keyed by name.
`request_definition.query_parameters.{key}`	object	No	Body	One entry per name.
`request_definition.query_parameters.{key}.type`	string	Yes	Body	One of: `string`, `integer`, `number`, `boolean`.
`request_definition.query_parameters.{key}.description`	string	No	Body	Human-readable description.
`request_definition.query_parameters.{key}.required`	boolean	No	Body	`true` if the model must supply a value.
`request_definition.query_parameters.{key}.binding`	object	No	Body	Fills a parameter from a fixed value or a runtime macro instead of the model.
`request_definition.query_parameters.{key}.binding.kind`	string	Yes	Body	One of: `default`, `macro`.
`request_definition.query_parameters.{key}.binding.value`	string	No	Body	Fixed value used when `kind` is `default`.
`request_definition.query_parameters.{key}.binding.macro`	string	No	Body	One of: `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`, `WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`, `WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID`, `INSTAGRAM_CONVERSATION_ID`.
`request_definition.headers`	object	No	Body	Request headers, keyed by name.
`request_definition.headers.{key}`	object	No	Body	One entry per name.
`request_definition.headers.{key}.type`	string	Yes	Body	One of: `string`, `integer`, `number`, `boolean`.
`request_definition.headers.{key}.description`	string	No	Body	Human-readable description.
`request_definition.headers.{key}.required`	boolean	No	Body	`true` if the model must supply a value.
`request_definition.headers.{key}.binding`	object	No	Body	Fills a parameter from a fixed value or a runtime macro instead of the model.
`request_definition.headers.{key}.binding.kind`	string	Yes	Body	One of: `default`, `macro`.
`request_definition.headers.{key}.binding.value`	string	No	Body	Fixed value used when `kind` is `default`.
`request_definition.headers.{key}.binding.macro`	string	No	Body	One of: `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`, `WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`, `WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID`, `INSTAGRAM_CONVERSATION_ID`.
`request_definition.body`	object	No	Body	JSON request body definition.
`request_definition.body.content_type`	string	Yes	Body	Always `application/json`.
`request_definition.body.params`	object	Yes	Body	Body fields, keyed by name.
`request_definition.body.params.{key}`	object	No	Body	One entry per name.
`request_definition.body.params.{key}.type`	string	Yes	Body	One of: `object`, `array`, `string`, `integer`, `number`, `boolean`.
`request_definition.body.params.{key}.description`	string	No	Body	Human-readable description.
`request_definition.body.params.{key}.required`	array of string	No	Body	Names of required child fields.
`request_definition.body.params.{key}.properties`	object	No	Body	Child field types, for objects.
`request_definition.body.params.{key}.properties.{key}`	string	No	Body	One entry per name.
`request_definition.body.params.{key}.items`	string	No	Body	Element type, for arrays.
`request_definition.body.params.{key}.binding`	object	No	Body	Fills a parameter from a fixed value or a runtime macro instead of the model.
`request_definition.body.params.{key}.binding.kind`	string	Yes	Body	One of: `default`, `macro`.
`request_definition.body.params.{key}.binding.value`	string	No	Body	Fixed value used when `kind` is `default`.
`request_definition.body.params.{key}.binding.macro`	string	No	Body	One of: `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`, `WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`, `WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID`, `INSTAGRAM_CONVERSATION_ID`.
`request_definition.body.required`	array of string	No	Body	Names of required body fields.
`user_auth_required`	boolean	Yes	Body	`true` if the tool needs the consumer's own login.
`user_auth_action_config`	object	No	Body	How the consumer's auth token is obtained or refreshed.
`user_auth_action_config.user_action_tool_type`	string	No	Body	One of: `auth`, `refresh`.
`user_auth_action_config.user_auth_token_path`	string	No	Body	JSON path to the token in the auth response.
`user_auth_action_config.refresh_token_path`	string	No	Body	JSON path to the refresh token.
`user_auth_action_config.expires_at_path`	string	No	Body	JSON path to the expiry.
`user_auth_action_config.expires_at_type`	string	No	Body	One of: `absolute`, `relative_seconds`.
`transformation_spec`	object / null	No	Body	On update, omit to keep the current spec or send `null` to remove it.
`transformation_spec.version`	integer	Yes	Body	Always `1`.
`transformation_spec.steps`	array of object	Yes	Body	Max 5 items.
`transformation_spec.steps[].kind`	string	Yes	Body	One of: `allowlist`, `case`, `catalog`, `decorate_url`, `dedupe`, `dehydrate`, `filter`, `first_nonempty`, `first_nonnull`, `first_nonzero`, `format`, `html_escape`, `lookup`, `math`, `proxy_image`, `reshape`, `shadow_allowlist`, `string_replace`, `truncate`.
`transformation_spec.steps[].target`	string	No	Body	Field the step writes to.
`transformation_spec.steps[].params`	string	No	Body	JSON-encoded step parameters.

Example request

curl --location --request POST 'https://partner.gupshup.io/partner/app/<appId>/bizai/agent_connectors/<connectorId>/tools' \
  --header 'Authorization: <PARTNER_APP_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "check_order_status",
  "description": "Retrieve order status and tracking information",
  "request_definition": {
    "method": "GET",
    "path": "/orders/{order_id}",
    "path_parameters": {
      "order_id": {
        "type": "string",
        "description": "Customer order ID",
        "required": true
      }
    }
  },
  "user_auth_required": false
}'

Response parameters — `201`

Parameter	Type	Description
`name`	string	Name.
`description`	string	Human-readable description.
`request_definition`	object	The outbound HTTP call the tool makes.
`request_definition.method`	string	One of: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`.
`request_definition.path`	string	e.g. `/orders/{order_id}`.
`request_definition.path_parameters`	object	Path placeholders, keyed by name.
`request_definition.path_parameters.{key}`	object	One entry per name.
`request_definition.path_parameters.{key}.type`	string	One of: `string`, `integer`, `number`, `boolean`.
`request_definition.path_parameters.{key}.description`	string	Human-readable description.
`request_definition.path_parameters.{key}.required`	boolean	`true` if the model must supply a value.
`request_definition.path_parameters.{key}.binding`	object	Fills a parameter from a fixed value or a runtime macro instead of the model.
`request_definition.path_parameters.{key}.binding.kind`	string	One of: `default`, `macro`.
`request_definition.path_parameters.{key}.binding.value`	string	Fixed value used when `kind` is `default`.
`request_definition.path_parameters.{key}.binding.macro`	string	One of: `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`, `WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`, `WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID`, `INSTAGRAM_CONVERSATION_ID`.
`request_definition.query_parameters`	object	Query parameters, keyed by name.
`request_definition.query_parameters.{key}`	object	One entry per name.
`request_definition.query_parameters.{key}.type`	string	One of: `string`, `integer`, `number`, `boolean`.
`request_definition.query_parameters.{key}.description`	string	Human-readable description.
`request_definition.query_parameters.{key}.required`	boolean	`true` if the model must supply a value.
`request_definition.query_parameters.{key}.binding`	object	Fills a parameter from a fixed value or a runtime macro instead of the model.
`request_definition.query_parameters.{key}.binding.kind`	string	One of: `default`, `macro`.
`request_definition.query_parameters.{key}.binding.value`	string	Fixed value used when `kind` is `default`.
`request_definition.query_parameters.{key}.binding.macro`	string	One of: `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`, `WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`, `WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID`, `INSTAGRAM_CONVERSATION_ID`.
`request_definition.headers`	object	Request headers, keyed by name.
`request_definition.headers.{key}`	object	One entry per name.
`request_definition.headers.{key}.type`	string	One of: `string`, `integer`, `number`, `boolean`.
`request_definition.headers.{key}.description`	string	Human-readable description.
`request_definition.headers.{key}.required`	boolean	`true` if the model must supply a value.
`request_definition.headers.{key}.binding`	object	Fills a parameter from a fixed value or a runtime macro instead of the model.
`request_definition.headers.{key}.binding.kind`	string	One of: `default`, `macro`.
`request_definition.headers.{key}.binding.value`	string	Fixed value used when `kind` is `default`.
`request_definition.headers.{key}.binding.macro`	string	One of: `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`, `WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`, `WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID`, `INSTAGRAM_CONVERSATION_ID`.
`request_definition.body`	object	JSON request body definition.
`request_definition.body.content_type`	string	Always `application/json`.
`request_definition.body.params`	object	Body fields, keyed by name.
`request_definition.body.params.{key}`	object	One entry per name.
`request_definition.body.params.{key}.type`	string	One of: `object`, `array`, `string`, `integer`, `number`, `boolean`.
`request_definition.body.params.{key}.description`	string	Human-readable description.
`request_definition.body.params.{key}.required`	array of string	Names of required child fields.
`request_definition.body.params.{key}.properties`	object	Child field types, for objects.
`request_definition.body.params.{key}.properties.{key}`	string	One entry per name.
`request_definition.body.params.{key}.items`	string	Element type, for arrays.
`request_definition.body.params.{key}.binding`	object	Fills a parameter from a fixed value or a runtime macro instead of the model.
`request_definition.body.params.{key}.binding.kind`	string	One of: `default`, `macro`.
`request_definition.body.params.{key}.binding.value`	string	Fixed value used when `kind` is `default`.
`request_definition.body.params.{key}.binding.macro`	string	One of: `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`, `WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`, `WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID`, `INSTAGRAM_CONVERSATION_ID`.
`request_definition.body.required`	array of string	Names of required body fields.
`user_auth_required`	boolean	`true` if the tool needs the consumer's own login.
`user_auth_action_config`	object	How the consumer's auth token is obtained or refreshed.
`user_auth_action_config.user_action_tool_type`	string	One of: `auth`, `refresh`.
`user_auth_action_config.user_auth_token_path`	string	JSON path to the token in the auth response.
`user_auth_action_config.refresh_token_path`	string	JSON path to the refresh token.
`user_auth_action_config.expires_at_path`	string	JSON path to the expiry.
`user_auth_action_config.expires_at_type`	string	One of: `absolute`, `relative_seconds`.
`transformation_spec`	object / null	On update, omit to keep the current spec or send `null` to remove it.
`transformation_spec.version`	integer	Always `1`.
`transformation_spec.steps`	array of object	Max 5 items.
`transformation_spec.steps[].kind`	string	One of: `allowlist`, `case`, `catalog`, `decorate_url`, `dedupe`, `dehydrate`, `filter`, `first_nonempty`, `first_nonnull`, `first_nonzero`, `format`, `html_escape`, `lookup`, `math`, `proxy_image`, `reshape`, `shadow_allowlist`, `string_replace`, `truncate`.
`transformation_spec.steps[].target`	string	Field the step writes to.
`transformation_spec.steps[].params`	string	JSON-encoded step parameters.
`id`	string	Resource id. Meta `pfbid…` id.

Example response — `201 Created`

{
  "id": "pfbid0ToolExampleId",
  "name": "check_order_status",
  "description": "Retrieve order status and tracking information",
  "request_definition": {
    "method": "GET",
    "path": "/orders/{order_id}",
    "path_parameters": {
      "order_id": {
        "type": "string",
        "description": "Customer order ID",
        "required": true
      }
    }
  },
  "user_auth_required": false
}

Error responses

400 Bad Request — The app is not live, or WASS does not consider it live.

{
  "message": "App is not live.",
  "status": "error"
}

400 Bad Request — The app has no phone number attached. Checked before the live check.

{
  "message": "Phone id not found for the given App",
  "status": "error"
}

401 Unauthorized — Authorization is missing or invalid, belongs to another app, or appId is unknown or not a UUID.

{
  "status": "error",
  "message": "Unauthorised access to the resource. Please review request parameters and headers and retry"
}

405 Method Not Allowed — Any method other than GET, POST, PUT or DELETE, e.g. PATCH.

{
  "status": "error",
  "message": "Request method 'PATCH' is not supported"
}

429 Too Many Requests — More than 30 /bizai/** requests in 60 seconds for this app. The 31st is rejected.

{
  "status": "error",
  "message": "Too Many Requests"
}

Responses

429

Per-app rate limit exceeded. Retry after the 60-second window.

Language

Credentials

Header

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json