# Channel connectors The following endpoints are part of the Connectors API. Channels are created by first installing a new connector. Connectors are responsible for linking the MessageBird Engagements platform to third party platforms. This documentation will provide details on how to interact with these endpoints. ## Create a connector {% hint style="info" %} **A-Sync** : this will start a background process that may require some time to complete. A Get call may be required to retrieve the final result. {% endhint %} ## POST /workspaces/{workspaceId}/connectors > Create a new connector from a template. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateConnectorReq":{"type":"object","title":"A request to instantiate a new connector from a template","additionalProperties":false,"properties":{"name":{"type":"string","title":"connector name"},"connectorTemplateRef":{"type":"string","title":"template to base this connector on by ref"},"arguments":{"title":"arguments to provide to each action invocation on this connector","$ref":"#/components/schemas/ConnectorArguments"},"securityArguments":{"$ref":"#/components/schemas/SecurityArgumentsMap"},"channelConversationalStatusEnabled":{"title":"Controls the default value for channel's conversational flag.","type":"boolean","nullable":true},"invitationToken":{"title":"Invitation token to allow installation of connectors that are not GA.","type":"string","nullable":true}},"required":["name"]},"ConnectorArguments":{"type":"object","title":"ConnectorArguments","description":"For SMS connectors (sms-messagebird:1), channelMessageType is required and must be one of promotional, transactional, conversational, emergency, 2fa.","additionalProperties":true,"nullable":true},"SecurityArgumentsMap":{"type":"object","title":"SecurityArgumentsMap","description":"Provide the arguments required by the security scheme(s) on the connector template.","additionalProperties":{"type":"object","title":"SecurityArguments","additionalProperties":{"type":"string"}},"nullable":true},"Connector":{"type":"object","title":"Connector","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of this connector."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace this connector belongs to."},"routingKey":{"type":"string","nullable":true},"name":{"type":"string","description":"The Name of this connector."},"region":{"type":"string","description":"The Region in which this connector was installed in."},"description":{"type":"string","description":"The Description of this connector."},"arguments":{"type":"object","additionalProperties":true,"description":"Pre-configured arguments for this connector.","nullable":true},"channel":{"nullable":true,"$ref":"#/components/schemas/ChannelConfig"},"number":{"nullable":true,"$ref":"#/components/schemas/NumberConfig"},"connectorTemplateSlug":{"type":"string","description":"The slug for the template this connector is based on."},"connectorTemplateRef":{"type":"string","description":"The ref for the template this connector is based on."},"dataFetching":{"$ref":"#/components/schemas/SyncConfig"},"dataCapture":{"type":"object","nullable":true,"properties":{"captureEndpoint":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time","description":"When the connector was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the connector was last updated."}},"required":["id","name","createdAt"]},"ChannelConfig":{"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"NumberConfig":{"type":"object","additionalProperties":false,"nullable":true,"required":["numberId","profileId"],"properties":{"profileId":{"type":"string","format":"uuid"},"numberId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"variables":{"type":"object"},"capabilities":{"type":"string","description":"Capabilities of a number. That would be represented with joined string of capabilities with comma."},"numberType":{"type":"string","description":"Type of the number; could be mobile, tollfree, local, etc."},"endpointType":{"type":"string","description":"Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc."},"country":{"type":"string","description":"Country code of the number."},"profileAttachments":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"capability":{"type":"string"},"profileId":{"type":"string"},"variables":{"type":"object","properties":{"connectorId":{"type":"string"}}}}}}}},"SyncConfig":{"type":"object","title":"The connector's data fetching synchronisation configuration and state.","additionalProperties":false,"properties":{"schedule":{"type":"string"},"streams":{"type":"array","nullable":true,"title":"streams that whould be fetched (names and incremental fetch config for each)","items":{"$ref":"#/components/schemas/StreamSyncConfig"}}}},"StreamSyncConfig":{"type":"object","title":"fetching configuration for a particular stream","additionalProperties":false,"properties":{"eventName":{"type":"string","title":"name of the event to push when records are fetched from that stream"},"streamName":{"type":"string","title":"name of the stream, as it appears in the catalog (see WorkflowStateForSync)"},"eventStreamName":{"type":"string","nullable":true,"title":"event that the stream will be mapped to"},"filter":{"type":"string","nullable":true,"title":"filter to apply to the records stream, record is included if the filter evaluates to true"},"initialState":{"type":"string","nullable":true,"title":"initial state to apply to the records stream"},"endCondition":{"type":"string","nullable":true,"title":"end condition to apply to the records stream, stops fetching when the condition evaluates to true"},"incremental":{"type":"boolean","title":"whether to fetch the contents of this stream incrementally"},"duplicatesFilterCapacity":{"type":"number","title":"size of the filter used to de-duplicate records"},"cursorField":{"type":"string","nullable":true,"title":"when fetching incrementally, and the source doesn't specify the cursor field, (JSON-)path of the field to use as a cursor field"}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors":{"post":{"operationId":"createConnector","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConnectorReq"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connector"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"workspace not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"connector already exists"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"invalid data provided"}},"summary":"Create a new connector from a template.","tags":["Connectors"]}}}} ``` ### Supported channel connectors Currently we support creating the following channel connectors {% tabs %} {% tab title="SMS" %} ### Properties | Property | Type | Description | | ---------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | connectorTemplateRef | string | Set as **sms-messagebird:1** | | name | string | The name of your connector e.g. My SMS channel | | arguments.phoneNumberId | string | The ID of the phone number to be installed. See | | arguments.useCaseId | string | The ID of the use case. Required for 10DLC numbers. See | | arguments.channelMessageType | string | The type of traffic that will be sent through this channel. For SMS connectors (`sms-messagebird:1`), it is a required field. `channelMessageType` is required and must be one of: `promotional`, `transactional`, `conversational`, `emergency`, `2fa`. | | channelConversationalStatusEnabled | boolean | If true incoming messages will create new conversations in Inbox | | | | | ### Example request ```json { "connectorTemplateRef": "sms-messagebird:1", "name": "My SMS channel", "arguments": { "phoneNumberId": "2cffb55c-120e-91a8-8f10-ed9d1b412d29", "useCaseId": "be123b02-dacf-31f9-b3e5-50b18260bc23", "channelMessageType": "promotional" }, "channelConversationalStatusEnabled": true } ``` {% endtab %} {% endtabs %} ## List connectors ## GET /workspaces/{workspaceId}/connectors > Get list of available connectors for this workspace. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"queryByTemplateRef":{"description":"Filter connectors by template ref","explode":false,"in":"query","name":"templateRef","required":false,"schema":{"type":"string"}},"queryLimit":{"description":"Limits the number of results to return","in":"query","name":"limit","schema":{"default":10,"maximum":100,"minimum":0,"type":"integer"}},"queryCursor":{"description":"Pagination token that keeps of track of the current position in the list","in":"query","name":"pageToken","schema":{"maxLength":8000,"type":"string"}},"queryDirection":{"description":"Order in which to retrieve the results","in":"query","name":"reverse","schema":{"default":false,"type":"boolean"}},"queryIncludeInternal":{"description":"Include internal ReleaseStatus in the result","in":"query","name":"includeInternal","schema":{"default":false,"type":"boolean"}}},"schemas":{"ConnectorList":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Connector"}}}},"Connector":{"type":"object","title":"Connector","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of this connector."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace this connector belongs to."},"routingKey":{"type":"string","nullable":true},"name":{"type":"string","description":"The Name of this connector."},"region":{"type":"string","description":"The Region in which this connector was installed in."},"description":{"type":"string","description":"The Description of this connector."},"arguments":{"type":"object","additionalProperties":true,"description":"Pre-configured arguments for this connector.","nullable":true},"channel":{"nullable":true,"$ref":"#/components/schemas/ChannelConfig"},"number":{"nullable":true,"$ref":"#/components/schemas/NumberConfig"},"connectorTemplateSlug":{"type":"string","description":"The slug for the template this connector is based on."},"connectorTemplateRef":{"type":"string","description":"The ref for the template this connector is based on."},"dataFetching":{"$ref":"#/components/schemas/SyncConfig"},"dataCapture":{"type":"object","nullable":true,"properties":{"captureEndpoint":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time","description":"When the connector was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the connector was last updated."}},"required":["id","name","createdAt"]},"ChannelConfig":{"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"NumberConfig":{"type":"object","additionalProperties":false,"nullable":true,"required":["numberId","profileId"],"properties":{"profileId":{"type":"string","format":"uuid"},"numberId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"variables":{"type":"object"},"capabilities":{"type":"string","description":"Capabilities of a number. That would be represented with joined string of capabilities with comma."},"numberType":{"type":"string","description":"Type of the number; could be mobile, tollfree, local, etc."},"endpointType":{"type":"string","description":"Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc."},"country":{"type":"string","description":"Country code of the number."},"profileAttachments":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"capability":{"type":"string"},"profileId":{"type":"string"},"variables":{"type":"object","properties":{"connectorId":{"type":"string"}}}}}}}},"SyncConfig":{"type":"object","title":"The connector's data fetching synchronisation configuration and state.","additionalProperties":false,"properties":{"schedule":{"type":"string"},"streams":{"type":"array","nullable":true,"title":"streams that whould be fetched (names and incremental fetch config for each)","items":{"$ref":"#/components/schemas/StreamSyncConfig"}}}},"StreamSyncConfig":{"type":"object","title":"fetching configuration for a particular stream","additionalProperties":false,"properties":{"eventName":{"type":"string","title":"name of the event to push when records are fetched from that stream"},"streamName":{"type":"string","title":"name of the stream, as it appears in the catalog (see WorkflowStateForSync)"},"eventStreamName":{"type":"string","nullable":true,"title":"event that the stream will be mapped to"},"filter":{"type":"string","nullable":true,"title":"filter to apply to the records stream, record is included if the filter evaluates to true"},"initialState":{"type":"string","nullable":true,"title":"initial state to apply to the records stream"},"endCondition":{"type":"string","nullable":true,"title":"end condition to apply to the records stream, stops fetching when the condition evaluates to true"},"incremental":{"type":"boolean","title":"whether to fetch the contents of this stream incrementally"},"duplicatesFilterCapacity":{"type":"number","title":"size of the filter used to de-duplicate records"},"cursorField":{"type":"string","nullable":true,"title":"when fetching incrementally, and the source doesn't specify the cursor field, (JSON-)path of the field to use as a cursor field"}}},"pagination":{"properties":{"nextPageToken":{"description":"The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.","type":"string"}},"type":"object"},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors":{"get":{"operationId":"listConnectors","parameters":[{"$ref":"#/components/parameters/queryByTemplateRef"},{"$ref":"#/components/parameters/queryLimit"},{"$ref":"#/components/parameters/queryCursor"},{"$ref":"#/components/parameters/queryDirection"},{"$ref":"#/components/parameters/queryIncludeInternal"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ConnectorList"},{"$ref":"#/components/schemas/pagination"}]}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"workspace not found"}},"summary":"Get list of available connectors for this workspace.","tags":["Connectors"]}}}} ``` ### Filter by channel connector template To filter connectors by a certain channel type use the templateRef as below: | Channel Connector | templateRef | | ------------------ | ------------------- | | SMS | sms-messagebird:1 | | WhatsApp | whatsapp:1 | | Instagram | instagram:1 | | Facebook messenger | facebook:1 | | Telegram | telegram:1 | | Line | line:1 | | Email | email-messagebird:1 | ## Get a connector ## GET /workspaces/{workspaceId}/connectors/{connectorId} > Show the details of a specific connector. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"Connector":{"type":"object","title":"Connector","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of this connector."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace this connector belongs to."},"routingKey":{"type":"string","nullable":true},"name":{"type":"string","description":"The Name of this connector."},"region":{"type":"string","description":"The Region in which this connector was installed in."},"description":{"type":"string","description":"The Description of this connector."},"arguments":{"type":"object","additionalProperties":true,"description":"Pre-configured arguments for this connector.","nullable":true},"channel":{"nullable":true,"$ref":"#/components/schemas/ChannelConfig"},"number":{"nullable":true,"$ref":"#/components/schemas/NumberConfig"},"connectorTemplateSlug":{"type":"string","description":"The slug for the template this connector is based on."},"connectorTemplateRef":{"type":"string","description":"The ref for the template this connector is based on."},"dataFetching":{"$ref":"#/components/schemas/SyncConfig"},"dataCapture":{"type":"object","nullable":true,"properties":{"captureEndpoint":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time","description":"When the connector was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the connector was last updated."}},"required":["id","name","createdAt"]},"ChannelConfig":{"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"NumberConfig":{"type":"object","additionalProperties":false,"nullable":true,"required":["numberId","profileId"],"properties":{"profileId":{"type":"string","format":"uuid"},"numberId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"variables":{"type":"object"},"capabilities":{"type":"string","description":"Capabilities of a number. That would be represented with joined string of capabilities with comma."},"numberType":{"type":"string","description":"Type of the number; could be mobile, tollfree, local, etc."},"endpointType":{"type":"string","description":"Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc."},"country":{"type":"string","description":"Country code of the number."},"profileAttachments":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"capability":{"type":"string"},"profileId":{"type":"string"},"variables":{"type":"object","properties":{"connectorId":{"type":"string"}}}}}}}},"SyncConfig":{"type":"object","title":"The connector's data fetching synchronisation configuration and state.","additionalProperties":false,"properties":{"schedule":{"type":"string"},"streams":{"type":"array","nullable":true,"title":"streams that whould be fetched (names and incremental fetch config for each)","items":{"$ref":"#/components/schemas/StreamSyncConfig"}}}},"StreamSyncConfig":{"type":"object","title":"fetching configuration for a particular stream","additionalProperties":false,"properties":{"eventName":{"type":"string","title":"name of the event to push when records are fetched from that stream"},"streamName":{"type":"string","title":"name of the stream, as it appears in the catalog (see WorkflowStateForSync)"},"eventStreamName":{"type":"string","nullable":true,"title":"event that the stream will be mapped to"},"filter":{"type":"string","nullable":true,"title":"filter to apply to the records stream, record is included if the filter evaluates to true"},"initialState":{"type":"string","nullable":true,"title":"initial state to apply to the records stream"},"endCondition":{"type":"string","nullable":true,"title":"end condition to apply to the records stream, stops fetching when the condition evaluates to true"},"incremental":{"type":"boolean","title":"whether to fetch the contents of this stream incrementally"},"duplicatesFilterCapacity":{"type":"number","title":"size of the filter used to de-duplicate records"},"cursorField":{"type":"string","nullable":true,"title":"when fetching incrementally, and the source doesn't specify the cursor field, (JSON-)path of the field to use as a cursor field"}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors/{connectorId}":{"get":{"operationId":"getConnector","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connector"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"connector not found"}},"summary":"Show the details of a specific connector.","tags":["Connectors"]}}}} ``` ### Check the readiness of a connector and its channel to send SMS ## GET /workspaces/{workspaceId}/connectors/{connectorId}/status > Show the status of a specific connector. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"ConnectorStatus":{"type":"object","properties":{"checks":{"$ref":"#/components/schemas/ConnectorStatusConfigCheck"},"channel":{"nullable":true,"type":"object","properties":{"channelId":{"type":"string","nullable":true,"format":"uuid"},"platformName":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"enum":["ok","pending","error","unknown"]},"stage":{"type":"string","nullable":true,"enum":["active","inactive","provisioning","deprovisioning","deprovisioned"]},"errorMessage":{"type":"string","nullable":true}}},"dataCapture":{"nullable":true,"type":"object","properties":{"status":{"type":"string","nullable":true,"enum":["ok","pending","error","unknown"]},"stage":{"type":"string","nullable":true,"enum":["active","inactive","provisioning","deprovisioning","deprovisioned"]},"errorMessage":{"type":"string","nullable":true}}},"dataFetching":{"nullable":true,"type":"object","properties":{"schedule":{"type":"string","nullable":true},"streams":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"enum":["ok","pending","error","unknown"]},"stage":{"type":"string","nullable":true,"enum":["active","inactive","provisioning","deprovisioning","deprovisioned"]},"disabled":{"type":"boolean"},"disabledAt":{"type":"string","nullable":true},"errorMessage":{"type":"string","nullable":true},"lastExecution":{"nullable":true,"type":"object","properties":{"status":{"type":"string"},"startedAt":{"nullable":true,"type":"string","format":"date-time"},"endedAt":{"nullable":true,"type":"string","format":"date-time"},"duration":{"nullable":true,"type":"number"},"errorMessage":{"nullable":true,"type":"string"}}}}},"engagements":{"nullable":true,"type":"object","properties":{"lakeletId":{"type":"string","nullable":true,"format":"uuid"},"status":{"type":"string","nullable":true,"enum":["ok","pending","error","unknown"]},"stage":{"type":"string","nullable":true,"enum":["active","inactive","provisioning","deprovisioning","deprovisioned"]},"errorMessage":{"type":"string","nullable":true}}},"number":{"nullable":true,"type":"object","properties":{"numberId":{"type":"string","nullable":true,"format":"uuid"},"profileId":{"type":"string","nullable":true,"format":"uuid"},"phoneNumber":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"enum":["ok","pending","error","unknown"]},"stage":{"type":"string","nullable":true,"enum":["active","inactive","provisioning","deprovisioning","deprovisioned"]},"errorMessage":{"type":"string","nullable":true}}},"dataFlows":{"nullable":true,"type":"object","properties":{"status":{"type":"string","nullable":true,"enum":["ok","pending","error","unknown"]},"stage":{"type":"string","nullable":true,"enum":["active","inactive","provisioning","deprovisioning","deprovisioned"]},"errorMessage":{"type":"string","nullable":true},"dataFlows":{"type":"object","additionalProperties":{"properties":{"id":{"type":"string","format":"uuid"},"disabled":{"type":"boolean"},"disabledAt":{"type":"string","format":"date-time"},"schedule":{"type":"string"},"lastRun":{"type":"object","properties":{"id":{"type":"string"},"dataFlowId":{"type":"string"},"workspaceId":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"},"duration":{"type":"integer"},"message":{"type":"string"}}}}}}}},"dataHubCatalog":{"nullable":true,"type":"object","properties":{"status":{"type":"string","nullable":true,"enum":["ok","pending","error","unknown"]},"stage":{"type":"string","nullable":true,"enum":["active","inactive","provisioning","deprovisioning","deprovisioned"]},"errorMessage":{"type":"string","nullable":true},"catalogs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"models":{"type":"array","items":{"type":"string"}}}}}}}}},"ConnectorStatusConfigCheck":{"type":"object","properties":{"runAt":{"type":"string","format":"date-time"},"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string","enum":["invalid","ok","warning","error","indeterminate"]},"assertions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["invalid","ok","warning","error","indeterminate"]},"message":{"type":"string"}}}}}}}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors/{connectorId}/status":{"get":{"operationId":"getConnectorStatus","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorStatus"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"connector not found"}},"summary":"Show the status of a specific connector.","tags":["Connectors"]}}}} ``` ## Delete a connector {% hint style="danger" %} Deleting a connector will also delete the associated channel. Messaging for the related channel connector will be interrupted. Be sure you want to delete the connector before proceeding {% endhint %} ## DELETE /workspaces/{workspaceId}/connectors/{connectorId} > Delete a specific connector. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors/{connectorId}":{"delete":{"operationId":"deleteConnector","responses":{"204":{"description":"OK"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"connector template still referenced"}},"summary":"Delete a specific connector.","tags":["Connectors"]}}}} ``` ## (Optional) create a workspace subscription to list to channel related events You can create a workspace subscription to listen to Channel Status changes and/or to be informed about new channel creations via webhooks ## Create a webhook subscription > To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL.\ > You can create multiple webhook subscriptions to route different types of events to various URLs as needed.\ > Event filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent.\ > If you want to handle multiple interactionTypes, you'll need to create separate webhook subscriptions for each.
```json {"openapi":"3.0.3","info":{"title":"Notifications","version":"1.0.0"},"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateWebhookSubscription":{"allOf":[{"type":"object","required":["service","event","url"],"additionalProperties":false,"properties":{"service":{"$ref":"#/components/schemas/WebhookService"},"event":{"$ref":"#/components/schemas/WebhookEvent"},"eventFilters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/WebhookEventFilter"},"description":"Filters to apply to the events that are sent to the webhook. This is a key-value list of filters that are specific to the service that the webhook is subscribed to.\nOne example would be a key of `channelId` and a value of a UUID (in string format) that represents a channel.\n"},"template":{"type":"string"},"url":{"$ref":"#/components/schemas/Url"},"signingKey":{"$ref":"#/components/schemas/SigningKey"}},"oneOf":[{"$ref":"#/components/schemas/EventFiltersChannels"},{"$ref":"#/components/schemas/EventFiltersNumbers"},{"$ref":"#/components/schemas/EventFiltersPayments"},{"$ref":"#/components/schemas/EventFiltersConversations"},{"$ref":"#/components/schemas/EventFiltersTemplates"}],"discriminator":{"propertyName":"service","mapping":{"channels":"#/components/schemas/EventFiltersChannels","numbers":"#/components/schemas/EventFiltersNumbers","payments":"#/components/schemas/EventFiltersPayments","conversations":"#/components/schemas/EventFiltersConversations","templates":"#/components/schemas/EventFiltersTemplates"}}}]},"WebhookService":{"type":"string","enum":["channels","numbers","payments","conversations","templates"],"description":"The service that the webhook is subscribed to. For example, to get events regarding channels, the service would be `channels`.\n"},"WebhookEvent":{"type":"string","description":"The event name identifies the webhook event, such as `sms.outbound` for notifications about SMS messages being sent.\n"},"WebhookEventFilter":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId","platformId","channelStatus","interactionType","messageStatus","status","eventDestination","navigatorId"]},"value":{"type":"string"}},"description":"Filters used to narrow down events sent to the webhook. For example, if you want to receive events for a specific platform,\na valid filterKey would be `platformId` with a value of `sms`.\n"},"Url":{"type":"string","pattern":"^https://([a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}(/[^\\s]*)?$","description":"The URL of the webhook is used to send events to the webhook. The URL must be a valid URL that respects the established pattern and is accessible from the internet.\n"},"SigningKey":{"type":"string","description":"The signing key for the webhook and can be used to verify the authenticity of the webhook.\n"},"EventFiltersChannels":{"type":"object","title":"Channels service filters","properties":{"service":{"type":"string","enum":["channels"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId"]},"value":{"type":"string","format":"uuid"}}},{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["messageStatus","interactionType","channelStatus","platformId","status"]},"value":{"type":"string"}}}]}}}},"EventFiltersNumbers":{"type":"object","title":"Numbers service filters","properties":{"service":{"type":"string","enum":["numbers"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"additionalProperties":false,"description":"The numbers service does not have any specific filters for its events.\n","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"EventFiltersPayments":{"type":"object","title":"Numbers service filters","properties":{"service":{"type":"string","enum":["payments"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"EventFiltersConversations":{"type":"object","title":"Conversations service filters","properties":{"service":{"type":"string","enum":["conversations"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["channelId"]},"value":{"type":"string","format":"uuid"}}}]}}}},"EventFiltersTemplates":{"type":"object","title":"Templates service filters","properties":{"service":{"type":"string","enum":["templates"]},"eventFilters":{"type":"array","nullable":true,"items":{"type":"object","required":["key","value"],"oneOf":[{"additionalProperties":false,"properties":{"key":{"type":"string","enum":["platformId"]},"value":{"type":"string"}}}]}}}},"WebhookSubscription":{"type":"object","required":["id","organizationId","workspaceId","service","event","url","status"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier for the webhook subscription. This identifier is used to reference the webhook subscription in other API calls.\n"},"organizationId":{"$ref":"#/components/schemas/WebhookOrganizationId"},"workspaceId":{"$ref":"#/components/schemas/WebhookWorkspaceId"},"service":{"$ref":"#/components/schemas/WebhookService"},"event":{"$ref":"#/components/schemas/WebhookEvent"},"eventFilters":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventFilter"}},"template":{"$ref":"#/components/schemas/Template"},"url":{"$ref":"#/components/schemas/Url"},"signingKey":{"$ref":"#/components/schemas/SigningKey"},"status":{"$ref":"#/components/schemas/WebhookSubscriptionStatus"},"statusReason":{"type":"string","description":"A human-readable explanation for the current status of the webhook subscription.\n"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookOrganizationId":{"type":"string","format":"uuid"},"WebhookWorkspaceId":{"type":"string","format":"uuid"},"Template":{"type":"string","description":"Used for our Exit APIs for Twilio and Sinch.\nMore information can be found [here](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/twilio-exit-api) for Twilio and [here](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/sinch-exit-api) for Sinch.\n"},"WebhookSubscriptionStatus":{"type":"string","enum":["active","inactive"]},"errorResponse":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions":{"post":{"summary":"Create a webhook subscription","description":"To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL.\nYou can create multiple webhook subscriptions to route different types of events to various URLs as needed.\nEvent filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent.\nIf you want to handle multiple interactionTypes, you'll need to create separate webhook subscriptions for each.\n","operationId":"createLegacyWebhookSubscription","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookSubscription"}}}},"responses":{"201":{"description":"The webhook subscription was created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Invalid HTTP request. The HTTP response should include details about the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}},"422":{"description":"The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}}}}}} ``` #### Channel creation Subscription The example below will create a workspace wide subscription tracking all channel creations. this will inform you of any new channel being created and will return you the number / sender `identifier` the `connectorId` and the `channelId` associated with it. ``` curl --location 'https://api.bird.com/organizations//workspaces//webhook-subscriptions' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "service": "channels", "event": "channel.created", "url": "myURL.com", "signingKey": "mysecretkey", "eventFilters": [ ] }' ``` #### Channel Updates Subscription The example below will create a workspace wide subscription tracking all updates regarding your channels. This is particularly useful when waiting for a channel to become active as a status update will always trigger an update event ``` curl --location 'https://api.bird.com/organizations//workspaces//webhook-subscriptions' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "service": "channels", "event": "channel.updated", "url": "myURL.com", "signingKey": "mysecretkey", "eventFilters": [ ] }' ```