> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://catena.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://catena.ferndocs.com/_mcp/server. # Create Group Message POST https://api.catenatelematics.com/v2/telematics/group-messages Content-Type: application/json Create a new group message. The message will be created asynchronously, and you can check the status of the operation using the returned operation ID. Reference: https://catena.ferndocs.com/api-reference/telematics/drivers-users/create-group-message ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Query parameters - `is_sync` (boolean, optional, default: false) — Whether to process the request synchronously. If `true`, Catena will attempt to create or update the resource immediately with the TSP and return the result in the response. When performing synchronous operations, you are responsible for handling any necessary retries in case of transient failures.If `false` (default), Catena will create an asynchronous operation, and you can check the status of the operation using the returned operation ID. ### Body (application/json) This endpoint expects a GroupMessageCreate. - `connection_id` (string, required) — Unique identifier of the connection at Catena Telematics which will be used to create this resource. A connection represents a Fleet/TSP pairing. - `sender_id` (string, required) — Identifier for the sender - `recipient_ids` (list of string, required) — Identifiers for the recipients - `message_text` (string, optional, nullable) — The content of the message - `priority` (enum, optional, nullable) — Optional priority for the message: low, medium, or high - Allowed values: `low`, `medium`, `high` ## Response ### 200 The group message was created successfully. - `partner_id` (string, required) — The ID of the partner that created the operation. - `connection_id` (string, required) — The ID of the connection - `resource` (enum, required) — The type of resource to operate on (e.g., vehicle, driver). - Allowed values: `asset`, `document`, `driver_association`, `driver_vehicle_association`, `driver_event_log`, `driver_safety_event`, `dvir_log`, `dvir_log_defect`, `engine_log`, `engine_status`, `fuel_transaction`, `fuel_card`, `fleet_info`, `hos_availability`, `hos_daily_log`, `hos_daily_snapshot`, `hos_event`, `hos_event_annotation`, `hos_event_attachment`, `hos_violation`, `ifta_summary`, `location_segment`, `message`, `group_message`, `user`, `vehicle`, `vehicle_location`, `vehicle_sensor`, `vehicle_region_segment`, `trailer`, `trailer_association`, `trailer_vehicle_association`, `trailer_location`, `trailer_status`, `workflow` - `operation_type` (enum, required) — The type of operation to perform (e.g., create, update). - Allowed values: `create`, `update` - `payload` (map from string to any, required) — The payload of the operation, containing the resource attributes to be created or updated. - `id` (string, optional) — Unique identifier for the resource operation. - `created_at` (datetime, optional) — Immutable: The datetime the record was created in Catena Telematics. - `updated_at` (datetime, optional) — The datetime the record was last modified in Catena Telematics. - `deleted_at` (datetime, optional, nullable) — The datetime the record was logically deleted from Catena Telematics. - `resource_id` (string, optional, nullable) — Unique identifier of the record. Can be `null` for create operations where the source does not exist yet. - `source_id` (string, optional, nullable) — The unique identifier of the resource in the source system. Required for update operations. - `status` (enum, optional) — The status of the operation - Allowed values: `pending`, `success`, `failed` - `logs` (list of ResourceOperationLog, optional) — Log entries for each attempt to execute this operation. ### 202 The request to create the group message has been accepted and is being processed. - `partner_id` (string, required) — The ID of the partner that created the operation. - `connection_id` (string, required) — The ID of the connection - `resource` (enum, required) — The type of resource to operate on (e.g., vehicle, driver). - Allowed values: `asset`, `document`, `driver_association`, `driver_vehicle_association`, `driver_event_log`, `driver_safety_event`, `dvir_log`, `dvir_log_defect`, `engine_log`, `engine_status`, `fuel_transaction`, `fuel_card`, `fleet_info`, `hos_availability`, `hos_daily_log`, `hos_daily_snapshot`, `hos_event`, `hos_event_annotation`, `hos_event_attachment`, `hos_violation`, `ifta_summary`, `location_segment`, `message`, `group_message`, `user`, `vehicle`, `vehicle_location`, `vehicle_sensor`, `vehicle_region_segment`, `trailer`, `trailer_association`, `trailer_vehicle_association`, `trailer_location`, `trailer_status`, `workflow` - `operation_type` (enum, required) — The type of operation to perform (e.g., create, update). - Allowed values: `create`, `update` - `payload` (map from string to any, required) — The payload of the operation, containing the resource attributes to be created or updated. - `id` (string, optional) — Unique identifier for the resource operation. - `created_at` (datetime, optional) — Immutable: The datetime the record was created in Catena Telematics. - `updated_at` (datetime, optional) — The datetime the record was last modified in Catena Telematics. - `deleted_at` (datetime, optional, nullable) — The datetime the record was logically deleted from Catena Telematics. - `resource_id` (string, optional, nullable) — Unique identifier of the record. Can be `null` for create operations where the source does not exist yet. - `source_id` (string, optional, nullable) — The unique identifier of the resource in the source system. Required for update operations. - `status` (enum, optional) — The status of the operation - Allowed values: `pending`, `success`, `failed` - `logs` (list of ResourceOperationLog, optional) — Log entries for each attempt to execute this operation. ## Errors ### 400 Bad Request Error Bad Request - `code` (integer, optional, default: 400) - `message` (string, optional, default: Bad Request) - `detail` (string, optional, nullable) ### 401 Unauthorized Error Unauthorized - `code` (integer, optional, default: 401) - `message` (string, optional, default: Unauthorized) - `detail` (string, optional, nullable) ### 403 Forbidden Error Forbidden - `code` (integer, optional, default: 403) - `message` (string, optional, default: Forbidden) - `detail` (string, optional, nullable) ### 404 Not Found Error Not Found - `code` (integer, optional, default: 404) - `message` (string, optional, default: Not Found) - `detail` (string, optional, nullable) ### 405 Method Not Allowed Error Method Not Allowed - `code` (integer, optional, default: 405) - `message` (string, optional, default: Method Not Allowed) - `detail` (string, optional, nullable) ### 409 Conflict Error Conflict - `code` (integer, optional, default: 409) - `message` (string, optional, default: Conflict) - `detail` (string, optional, nullable) ### 422 Unprocessable Entity Error Unprocessable Entity - `code` (integer, optional, default: 422) - `message` (string, optional, default: Invalid Request Body) - `detail` (list of ValidationErrorDetail, optional, nullable) ### 429 Too Many Requests Error Too Many Requests - `code` (integer, optional, default: 429) - `message` (string, optional, default: Too Many Requests) - `detail` (RetryAfterDetail, optional, nullable) ### 500 Internal Server Error Internal Server Error - `message` (string, optional, default: Internal Server Error) ### 501 Not Implemented Error Not Implemented - `code` (integer, optional, default: 501) - `message` (string, optional, default: Not Implemented) - `detail` (string, optional, nullable) ### 502 Bad Gateway Error The request to create the group message could not be processed at this time. Please see the response for more details. - `partner_id` (string, required) — The ID of the partner that created the operation. - `connection_id` (string, required) — The ID of the connection - `resource` (enum, required) — The type of resource to operate on (e.g., vehicle, driver). - Allowed values: `asset`, `document`, `driver_association`, `driver_vehicle_association`, `driver_event_log`, `driver_safety_event`, `dvir_log`, `dvir_log_defect`, `engine_log`, `engine_status`, `fuel_transaction`, `fuel_card`, `fleet_info`, `hos_availability`, `hos_daily_log`, `hos_daily_snapshot`, `hos_event`, `hos_event_annotation`, `hos_event_attachment`, `hos_violation`, `ifta_summary`, `location_segment`, `message`, `group_message`, `user`, `vehicle`, `vehicle_location`, `vehicle_sensor`, `vehicle_region_segment`, `trailer`, `trailer_association`, `trailer_vehicle_association`, `trailer_location`, `trailer_status`, `workflow` - `operation_type` (enum, required) — The type of operation to perform (e.g., create, update). - Allowed values: `create`, `update` - `payload` (map from string to any, required) — The payload of the operation, containing the resource attributes to be created or updated. - `id` (string, optional) — Unique identifier for the resource operation. - `created_at` (datetime, optional) — Immutable: The datetime the record was created in Catena Telematics. - `updated_at` (datetime, optional) — The datetime the record was last modified in Catena Telematics. - `deleted_at` (datetime, optional, nullable) — The datetime the record was logically deleted from Catena Telematics. - `resource_id` (string, optional, nullable) — Unique identifier of the record. Can be `null` for create operations where the source does not exist yet. - `source_id` (string, optional, nullable) — The unique identifier of the resource in the source system. Required for update operations. - `status` (enum, optional) — The status of the operation - Allowed values: `pending`, `success`, `failed` - `logs` (list of ResourceOperationLog, optional) — Log entries for each attempt to execute this operation. ## Types ### ResourceOperationLog API response model for a resource operation log entry. - `id` (string, required) — Unique identifier for the log entry. - `created_at` (datetime, required) — Timestamp when the log entry was created. - `updated_at` (datetime, required) — Timestamp when the log entry was last updated. - `resource_operation_id` (string, required) — The ID of the resource operation this log entry belongs to. - `status` (enum, required) — The status of the operation attempt. - Allowed values: `success`, `failed` - `error_type` (enum, optional, nullable) — The type of error that occurred, if any. - Allowed values: `auth`, `validation`, `network`, `tsp` - `error_details` (string, optional, nullable) — Detailed information about the error, if any. - `response_status_code` (integer, optional, nullable) — HTTP status code returned by the TSP, if available. - `response_headers` (map from string to string, optional, nullable) — HTTP response headers from the TSP (e.g. rate limit state). ### ValidationErrorDetail - `path` (string, required) - `input` (string, required) - `message` (string, required) - `error_type` (string, required) ### RetryAfterDetail - `retry_after_seconds` (integer, required) - `message` (string, required) ## Examples ### Example 1 **Request** ```json { "connection_id": "string", "sender_id": "string", "recipient_ids": [ "string" ] } ``` **Response** ```json { "partner_id": "string", "connection_id": "string", "resource": "asset", "operation_type": "create", "payload": {}, "id": "string", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "deleted_at": "2024-01-15T09:30:00Z", "resource_id": "string", "source_id": "string", "status": "pending", "logs": [ { "id": "string", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "resource_operation_id": "string", "status": "success", "error_type": "auth", "error_details": "string", "response_status_code": 1, "response_headers": {} } ] } ``` **SDK Code** ```python import requests url = "https://api.catenatelematics.com/v2/telematics/group-messages" payload = { "connection_id": "string", "sender_id": "string", "recipient_ids": ["string"] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.catenatelematics.com/v2/telematics/group-messages'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"connection_id":"string","sender_id":"string","recipient_ids":["string"]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.catenatelematics.com/v2/telematics/group-messages" payload := strings.NewReader("{\n \"connection_id\": \"string\",\n \"sender_id\": \"string\",\n \"recipient_ids\": [\n \"string\"\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.catenatelematics.com/v2/telematics/group-messages") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"connection_id\": \"string\",\n \"sender_id\": \"string\",\n \"recipient_ids\": [\n \"string\"\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.catenatelematics.com/v2/telematics/group-messages") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"connection_id\": \"string\",\n \"sender_id\": \"string\",\n \"recipient_ids\": [\n \"string\"\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.catenatelematics.com/v2/telematics/group-messages', [ 'body' => '{ "connection_id": "string", "sender_id": "string", "recipient_ids": [ "string" ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.catenatelematics.com/v2/telematics/group-messages"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"connection_id\": \"string\",\n \"sender_id\": \"string\",\n \"recipient_ids\": [\n \"string\"\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "connection_id": "string", "sender_id": "string", "recipient_ids": ["string"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.catenatelematics.com/v2/telematics/group-messages")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Example 2 **Request** ```json { "connection_id": "string", "sender_id": "string", "recipient_ids": [ "string" ] } ``` **Response** ```json { "partner_id": "string", "connection_id": "string", "resource": "asset", "operation_type": "create", "payload": {}, "id": "string", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "deleted_at": "2024-01-15T09:30:00Z", "resource_id": "string", "source_id": "string", "status": "pending", "logs": [ { "id": "string", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "resource_operation_id": "string", "status": "success", "error_type": "auth", "error_details": "string", "response_status_code": 1, "response_headers": {} } ] } ``` **SDK Code** ```python import requests url = "https://api.catenatelematics.com/v2/telematics/group-messages" payload = { "connection_id": "string", "sender_id": "string", "recipient_ids": ["string"] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.catenatelematics.com/v2/telematics/group-messages'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"connection_id":"string","sender_id":"string","recipient_ids":["string"]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.catenatelematics.com/v2/telematics/group-messages" payload := strings.NewReader("{\n \"connection_id\": \"string\",\n \"sender_id\": \"string\",\n \"recipient_ids\": [\n \"string\"\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.catenatelematics.com/v2/telematics/group-messages") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"connection_id\": \"string\",\n \"sender_id\": \"string\",\n \"recipient_ids\": [\n \"string\"\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.catenatelematics.com/v2/telematics/group-messages") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"connection_id\": \"string\",\n \"sender_id\": \"string\",\n \"recipient_ids\": [\n \"string\"\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.catenatelematics.com/v2/telematics/group-messages', [ 'body' => '{ "connection_id": "string", "sender_id": "string", "recipient_ids": [ "string" ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.catenatelematics.com/v2/telematics/group-messages"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"connection_id\": \"string\",\n \"sender_id\": \"string\",\n \"recipient_ids\": [\n \"string\"\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "connection_id": "string", "sender_id": "string", "recipient_ids": ["string"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.catenatelematics.com/v2/telematics/group-messages")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```