> For the complete documentation index, see [llms.txt](/docs/llms.txt) # Generic Messenger | FusionAuth Docs Learn about the APIs for creating, retrieving, and updating Generic Messengers. # Generic Messenger Available since version `1.26.0` The following APIs are provided to manage Generic Messengers. ## Create the Generic Messenger[#](#create-the-generic-messenger) ### Request[#](#request) Create a Generic Messenger with a randomly generated Id. POST/api/messenger OpenAPI Spec Create a Generic Messenger with the provided unique Id. POST/api/messenger/{messengerId} OpenAPI Spec The **type** in the request JSON is used to determine that you are creating the Generic Messenger. #### Request Parameters[#](#request-parameters) `messengerId`UUIDoptionalDefaults to secure random UUID The Id to use for the new Messenger. If not specified a secure random UUID will be generated. #### Request Body[#](#request-body) `messenger.connectTimeout`Integerrequired The connect timeout for the HTTP connection, in milliseconds. Value must be greater than `0`. `messenger.data`Objectoptional An object that can hold any information about the Messenger that should be persisted. `messenger.debug`BooleanoptionalDefaults to false If debug is enabled, an event log is created to assist in debugging messenger errors. `messenger.headers`Objectoptional An object that can hold HTTPHeader key and value pairs. `messenger.httpAuthenticationPassword`Stringoptional The basic authentication password to use for requests to the Messenger. `messenger.httpAuthenticationUsername`Stringoptional The basic authentication username to use for requests to the Messenger. `messenger.messageTypes`ArrayoptionalDefaults to \["SMS"\]Available since 1.65.0 The set of message types this messenger can send. Supported values include: * `SMS` * `Voice` `messenger.name`Stringrequired The unique Messenger name. `messenger.readTimeout`Integerrequired The read timeout for the HTTP connection, in milliseconds. Value must be greater than `0`. `messenger.sslCertificateId`UUIDoptional The Id of an existing [Key](/docs/apis/keys). The X.509 certificate is used for client certificate authentication in requests. `messenger.type`Stringrequired This field must be set to `Generic`. `messenger.url`Stringrequired The fully qualified URL of the endpoint that will accept requests from FusionAuth. *Example Generic Messenger Request JSON* ``` { "messenger": { "connectTimeout": 1000, "data": { "foo": "bar" }, "debug": false, "headers": { "Content-Type": "application/json" }, "httpAuthenticationPassword": "password", "httpAuthenticationUsername": "user-login", "messageTypes": [ "SMS", "Voice" ], "name": "Generic Messenger", "readTimeout": 1000, "sslCertificate": "e31e242b-4eca-4309-921f-48cb72ec9bfb", "type": "Generic", "url": "https://www.example.com/webhook" } } ``` ### Response[#](#response) *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. The response will contain a JSON body. | | 400 | The request was invalid and/or malformed. The response will contain an [Errors](/docs/apis/errors) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. | | 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). | | 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. | #### Response Body[#](#response-body) `messenger.connectTimeout`Integer The connect timeout for the HTTP connection, in milliseconds. `messenger.data`Object An object that can hold any information about the Messenger that should be persisted. `messenger.debug`Boolean If debug is enabled, an event log is created to assist in debugging messenger errors. `messenger.headers`Object An object that can hold HTTPHeader key and value pairs. `messenger.httpAuthenticationPassword`String The basic authentication password to use for requests to the Messenger. `messenger.httpAuthenticationUsername`String The basic authentication username to use for requests to the Messenger. `messenger.id`UUID The unique Id of the Messenger. `messenger.insertInstant`Long The [instant](/docs/reference/data-types#instants) when the Messenger was created. `messenger.lastUpdateInstant`Long The [instant](/docs/reference/data-types#instants) when the Messenger was last updated. `messenger.messageTypes`ArrayAvailable since 1.65.0 The set of message types this messenger can send. `messenger.name`String The unique Messenger name. `messenger.readTimeout`Integer The read timeout for the HTTP connection, in milliseconds. `messenger.sslCertificateId`UUID The Id of an existing [Key](/docs/apis/keys). The X.509 certificate is used for client certificate authentication in requests to the Messenger. `messenger.transport`StringAvailable since 1.26.0 Deprecated. This legacy field remains for backward compatibility. Use `messenger.messageTypes` instead. `messenger.type`String This field will always be `Generic`. `messenger.url`String The fully qualified URL of the endpoint that will accept requests from FusionAuth. *Example Generic Messenger Response JSON* ``` { "messenger": { "connectTimeout": 1000, "data": { "foo": "bar" }, "debug": false, "headers": { "Content-Type": "application/json" }, "httpAuthenticationPassword": "password", "httpAuthenticationUsername": "user-login", "id": "2d5acca6-23d5-423f-ac7b-b70f50b54498", "insertInstant": 1562189072183, "lastUpdateInstant": 1562189072183, "messageTypes": [ "SMS", "Voice" ], "name": "Generic Messenger", "readTimeout": 1000, "sslCertificate": "e31e242b-4eca-4309-921f-48cb72ec9bfb", "transport": "sms", "type": "Generic", "url": "https://www.example.com/webhook" } } ``` ## Retrieve the Generic Messenger[#](#retrieve-the-generic-messenger) ### Request[#](#request-1) Retrieve the Generic Messenger by Id GET/api/messenger/{messengerId} OpenAPI Spec #### Request Parameters[#](#request-parameters-1) `messengerId`UUIDrequired The Id of the Messenger to retrieve. ### Response[#](#response-1) *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. The response will contain a JSON body. | | 400 | The request was invalid and/or malformed. The response will contain an [Errors](/docs/apis/errors) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. | | 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). | | 404 | The object you requested doesn't exist. The response will be empty. | | 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. | #### Response Body[#](#response-body) `messenger.connectTimeout`Integer The connect timeout for the HTTP connection, in milliseconds. `messenger.data`Object An object that can hold any information about the Messenger that should be persisted. `messenger.debug`Boolean If debug is enabled, an event log is created to assist in debugging messenger errors. `messenger.headers`Object An object that can hold HTTPHeader key and value pairs. `messenger.httpAuthenticationPassword`String The basic authentication password to use for requests to the Messenger. `messenger.httpAuthenticationUsername`String The basic authentication username to use for requests to the Messenger. `messenger.id`UUID The unique Id of the Messenger. `messenger.insertInstant`Long The [instant](/docs/reference/data-types#instants) when the Messenger was created. `messenger.lastUpdateInstant`Long The [instant](/docs/reference/data-types#instants) when the Messenger was last updated. `messenger.messageTypes`ArrayAvailable since 1.65.0 The set of message types this messenger can send. `messenger.name`String The unique Messenger name. `messenger.readTimeout`Integer The read timeout for the HTTP connection, in milliseconds. `messenger.sslCertificateId`UUID The Id of an existing [Key](/docs/apis/keys). The X.509 certificate is used for client certificate authentication in requests to the Messenger. `messenger.transport`StringAvailable since 1.26.0 Deprecated. This legacy field remains for backward compatibility. Use `messenger.messageTypes` instead. `messenger.type`String This field will always be `Generic`. `messenger.url`String The fully qualified URL of the endpoint that will accept requests from FusionAuth. *Example Generic Messenger Response JSON* ``` { "messenger": { "connectTimeout": 1000, "data": { "foo": "bar" }, "debug": false, "headers": { "Content-Type": "application/json" }, "httpAuthenticationPassword": "password", "httpAuthenticationUsername": "user-login", "id": "2d5acca6-23d5-423f-ac7b-b70f50b54498", "insertInstant": 1562189072183, "lastUpdateInstant": 1562189072183, "messageTypes": [ "SMS", "Voice" ], "name": "Generic Messenger", "readTimeout": 1000, "sslCertificate": "e31e242b-4eca-4309-921f-48cb72ec9bfb", "transport": "sms", "type": "Generic", "url": "https://www.example.com/webhook" } } ``` ## Update the Generic Messenger[#](#update-the-generic-messenger) This API is used to update an existing Generic Messenger. You must specify all of the properties of the Generic Messenger when calling this API with the `PUT` HTTP method. When used with `PUT`, this API doesn't merge the existing Generic Messenger and your new data. It replaces the existing Generic Messenger with your new data. Utilize the `PATCH` HTTP method to send specific changes to merge into an existing Generic Messenger. ### Request[#](#request-2) Update the Generic Messenger by Id PUT/api/messenger/{messengerId} OpenAPI Spec PATCH/api/messenger/{messengerId} OpenAPI Spec For backward compatibility, the `PATCH` method accepts the same media type (specified by a `Content-Type` of `application/json`) and body as the `PUT` request. You can also use the following media types for different behavior: * [JSON Patch/RFC 6902](https://www.rfc-editor.org/rfc/rfc6902): `application/json-patch+json` * [JSON Merge Patch/RFC 7396](https://www.rfc-editor.org/rfc/rfc7396): `merge-patch+json` For details, see the [PATCH documentation](/docs/apis/#the-patch-http-method). Using a media type of `application/json` merges the provided request parameters into the existing object. As a result, all parameters are optional with `PATCH`: only provide the values you want to change. To remove a value, provide a `null` value. Patching an `Array` appends all values in the new list to the old list. #### Request Parameters[#](#request-parameters-2) `messengerId`UUIDrequired The Id of the Messenger to update. #### Request Body[#](#request-body) `messenger.connectTimeout`Integerrequired The connect timeout for the HTTP connection, in milliseconds. Value must be greater than `0`. `messenger.data`Objectoptional An object that can hold any information about the Messenger that should be persisted. `messenger.debug`BooleanoptionalDefaults to false If debug is enabled, an event log is created to assist in debugging messenger errors. `messenger.headers`Objectoptional An object that can hold HTTPHeader key and value pairs. `messenger.httpAuthenticationPassword`Stringoptional The basic authentication password to use for requests to the Messenger. `messenger.httpAuthenticationUsername`Stringoptional The basic authentication username to use for requests to the Messenger. `messenger.messageTypes`ArrayoptionalDefaults to \["SMS"\]Available since 1.65.0 The set of message types this messenger can send. Supported values include: * `SMS` * `Voice` `messenger.name`Stringrequired The unique Messenger name. `messenger.readTimeout`Integerrequired The read timeout for the HTTP connection, in milliseconds. Value must be greater than `0`. `messenger.sslCertificateId`UUIDoptional The Id of an existing [Key](/docs/apis/keys). The X.509 certificate is used for client certificate authentication in requests. `messenger.type`Stringrequired This field must be set to `Generic`. `messenger.url`Stringrequired The fully qualified URL of the endpoint that will accept requests from FusionAuth. *Example Generic Messenger Request JSON* ``` { "messenger": { "connectTimeout": 1000, "data": { "foo": "bar" }, "debug": false, "headers": { "Content-Type": "application/json" }, "httpAuthenticationPassword": "password", "httpAuthenticationUsername": "user-login", "messageTypes": [ "SMS", "Voice" ], "name": "Generic Messenger", "readTimeout": 1000, "sslCertificate": "e31e242b-4eca-4309-921f-48cb72ec9bfb", "type": "Generic", "url": "https://www.example.com/webhook" } } ``` ### Response[#](#response-2) The response for this API contains the Generic Messenger. *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. The response will contain a JSON body. | | 400 | The request was invalid and/or malformed. The response will contain an [Errors](/docs/apis/errors) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. | | 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). | | 404 | The object you are trying to update doesn't exist. The response will be empty. | | 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. | #### Response Body[#](#response-body) `messenger.connectTimeout`Integer The connect timeout for the HTTP connection, in milliseconds. `messenger.data`Object An object that can hold any information about the Messenger that should be persisted. `messenger.debug`Boolean If debug is enabled, an event log is created to assist in debugging messenger errors. `messenger.headers`Object An object that can hold HTTPHeader key and value pairs. `messenger.httpAuthenticationPassword`String The basic authentication password to use for requests to the Messenger. `messenger.httpAuthenticationUsername`String The basic authentication username to use for requests to the Messenger. `messenger.id`UUID The unique Id of the Messenger. `messenger.insertInstant`Long The [instant](/docs/reference/data-types#instants) when the Messenger was created. `messenger.lastUpdateInstant`Long The [instant](/docs/reference/data-types#instants) when the Messenger was last updated. `messenger.messageTypes`ArrayAvailable since 1.65.0 The set of message types this messenger can send. `messenger.name`String The unique Messenger name. `messenger.readTimeout`Integer The read timeout for the HTTP connection, in milliseconds. `messenger.sslCertificateId`UUID The Id of an existing [Key](/docs/apis/keys). The X.509 certificate is used for client certificate authentication in requests to the Messenger. `messenger.transport`StringAvailable since 1.26.0 Deprecated. This legacy field remains for backward compatibility. Use `messenger.messageTypes` instead. `messenger.type`String This field will always be `Generic`. `messenger.url`String The fully qualified URL of the endpoint that will accept requests from FusionAuth. *Example Generic Messenger Response JSON* ``` { "messenger": { "connectTimeout": 1000, "data": { "foo": "bar" }, "debug": false, "headers": { "Content-Type": "application/json" }, "httpAuthenticationPassword": "password", "httpAuthenticationUsername": "user-login", "id": "2d5acca6-23d5-423f-ac7b-b70f50b54498", "insertInstant": 1562189072183, "lastUpdateInstant": 1562189072183, "messageTypes": [ "SMS", "Voice" ], "name": "Generic Messenger", "readTimeout": 1000, "sslCertificate": "e31e242b-4eca-4309-921f-48cb72ec9bfb", "transport": "sms", "type": "Generic", "url": "https://www.example.com/webhook" } } ``` ## Delete the Generic Messenger[#](#delete-the-generic-messenger) ### Request[#](#request-3) Delete the Generic Messenger by Id DELETE/api/messenger/{messengerId} OpenAPI Spec `messengerId`UUIDrequired The Id of the Messenger to delete. ### Response[#](#response-3) This API does not return a JSON response body. *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. | | 400 | The request was invalid and/or malformed. The response will contain an [Errors](/docs/apis/errors) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. | | 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). | | 404 | The object you requested doesn't exist. The response will be empty. | | 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |