Update connector tool

put

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

Full replace. Every required field must be sent.

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.
`toolId`	string	Yes	Path	Connector tool 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 PUT 'https://partner.gupshup.io/partner/app/<appId>/bizai/agent_connectors/<connectorId>/tools/<toolId>' \
  --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 — `200`

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 — `200 OK`

{
  "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