Create connector

Time	Status	User Agent
Retrieving recent requests…

Time

Status

User Agent

Retrieving recent requests…

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`.
`name`	string	Yes	Body	Unique per app.
`description`	string	Yes	Body	Human-readable description.
`base_url`	string	Yes	Body	Root URL the connector calls.
`connector_protocol`	string	No	Body	One of: `HTTP`, `MCP`. Default `HTTP`.
`auth_type`	string	Yes	Body	The only supported values. `connector_protocol` cannot change after creation. One of: `OAUTH2_CLIENT_CREDENTIALS`, `API_KEY`, `NONE`.
`auth_config`	object	No	Body	Set the block matching `auth_type`.
`auth_config.api_key`	object	No	Body	At least one of the three lists must be non-empty.
`auth_config.api_key.headers`	array of object	No	Body	Entries sent as HTTP headers.
`auth_config.api_key.headers[].field_name`	string	Yes	Body	Header, query or body field name.
`auth_config.api_key.headers[].value`	string	Yes	Body	Write-only; never returned.
`auth_config.api_key.headers[].prefix`	string	No	Body	e.g. `Bearer` .
`auth_config.api_key.query_params`	array of object	No	Body	Entries sent as query parameters.
`auth_config.api_key.query_params[].field_name`	string	Yes	Body	Header, query or body field name.
`auth_config.api_key.query_params[].value`	string	Yes	Body	Write-only; never returned.
`auth_config.api_key.query_params[].prefix`	string	No	Body	e.g. `Bearer` .
`auth_config.api_key.body_params`	array of object	No	Body	Entries sent in the request body.
`auth_config.api_key.body_params[].field_name`	string	Yes	Body	Header, query or body field name.
`auth_config.api_key.body_params[].value`	string	Yes	Body	Write-only; never returned.
`auth_config.api_key.body_params[].prefix`	string	No	Body	e.g. `Bearer` .
`auth_config.oauth2_client_credentials`	object	No	Body	OAuth 2.0 client-credentials settings.
`auth_config.oauth2_client_credentials.token_url`	string	Yes	Body	OAuth token endpoint.
`auth_config.oauth2_client_credentials.scopes_to_request`	array of string	No	Body	OAuth scopes to request.
`auth_config.oauth2_client_credentials.token_request_content_type`	string	No	Body	One of: `application/x-www-form-urlencoded`, `application/json`.
`auth_config.oauth2_client_credentials.client_id`	string	Yes	Body	OAuth client id.
`auth_config.oauth2_client_credentials.client_secret`	string	Yes	Body	Write-only; never returned.
`user_auth_injection_config`	object	No	Body	Where the consumer's own auth token is injected on outbound calls.
`user_auth_injection_config.location`	string	Yes	Body	One of: `body`, `headers`, `path`, `query`.
`user_auth_injection_config.field_name`	string	Yes	Body	Header, query or body field name.
`user_auth_injection_config.prefix`	string	Yes	Body	Text placed before the value, e.g. `Bearer` .
`requires_certificate`	boolean	No	Body	`true` if outbound calls need a client certificate (mTLS).

Example request

curl --location --request POST 'https://partner.gupshup.io/partner/app/<appId>/bizai/agent_connectors' \
  --header 'Authorization: <PARTNER_APP_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Shopify Order Management",
  "description": "Connects to Shopify API for managing customer orders and inventory",
  "base_url": "https://api.shopify.com",
  "connector_protocol": "HTTP",
  "auth_type": "API_KEY",
  "auth_config": {
    "api_key": {
      "headers": [
        {
          "field_name": "X-Shopify-Access-Token",
          "value": "your-token",
          "prefix": ""
        }
      ]
    }
  },
  "requires_certificate": false
}'

Response parameters — `201`

Parameter	Type	Description
`id`	string	Resource id. Meta `pfbid…` id.
`name`	string	Name.
`description`	string	Human-readable description.
`base_url`	string	Root URL the connector calls.
`connector_protocol`	string	One of: `HTTP`, `MCP`.
`auth_type`	string	One of: `OAUTH2_CLIENT_CREDENTIALS`, `API_KEY`, `NONE`.
`auth_config`	object	Credentials for the chosen `auth_type`.
`user_auth_injection_config`	object	Where the consumer's own auth token is injected on outbound calls.
`user_auth_injection_config.location`	string	One of: `body`, `headers`, `path`, `query`.
`user_auth_injection_config.field_name`	string	Header, query or body field name.
`user_auth_injection_config.prefix`	string	Text placed before the value, e.g. `Bearer` .
`connection_status`	object	Whether the connector's credentials work.
`connection_status.status`	string	One of: `PENDING_OAUTH`, `ACTIVE`, `EXPIRED`, `ERROR`.
`connection_status.error_message`	string	Error text.
`mcp_tool_sync`	object / null	Null for HTTP connectors.
`mcp_tool_sync.status`	string	One of: `ERROR`, `PENDING`, `READY`.
`mcp_tool_sync.last_attempted_at`	integer	Last attempt, Unix seconds.
`mcp_tool_sync.last_successful_at`	integer	Last success, Unix seconds.
`mcp_tool_sync.fingerprint`	string	Hash identifying the stored value.
`mcp_tool_sync.tool_count`	integer	Number of tools discovered.
`mtls_config`	object	Client certificate status. The private key is never returned.
`mtls_config.has_certificate`	boolean	`true` if a certificate is stored.
`mtls_config.fingerprint`	string	Hash identifying the stored value.
`mtls_config.expires_at`	integer	Expiry, Unix seconds.
`mtls_config.subject`	string	Certificate subject.
`mtls_config.client_certificate`	string	Stored client certificate, PEM.
`mtls_config.ca_certificate`	string	Stored CA chain, PEM.

Example response — `201 Created`

{
  "id": "pfbid0ConnectorExampleId",
  "name": "Shopify Order Management",
  "description": "Connects to Shopify API for managing customer orders and inventory",
  "base_url": "https://api.shopify.com",
  "connector_protocol": "HTTP",
  "auth_type": "API_KEY",
  "auth_config": {
    "api_key": {
      "headers": [
        {
          "field_name": "X-Shopify-Access-Token",
          "prefix": ""
        }
      ]
    }
  },
  "connection_status": {
    "status": "ACTIVE"
  },
  "mcp_tool_sync": null,
  "mtls_config": {
    "has_certificate": 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"
}

Request parameters

Example request

Response parameters — 201

Example response — 201 Created

Error responses

201Connector created.

400The agent has not been onboarded, or the connector request is invalid.

401Missing, invalid, or foreign-app token. Raised by Partner Portal before any forwarding.

409A connector with this name already exists on the app.

Response parameters — `201`

Example response — `201 Created`