Post a video to a group

Upload a video and its thumbnail, then post it to a group with a caption, mentions, questions, or link-out cards.

Posting takes two steps: upload the files to Genuin's media storage through signed URLs, then call this endpoint with the file names. The post appears in the group feed and the community right away, under the account behind your access token. That account has to be allowed to post in the group by its "who can post" setting. See Generate an access token for the token.

Endpoint

POST /api/thirdparty/users/conversation/reply

Environment	Base URL
Production	https://api.begenuin.com
QA	https://api.qa.begenuin.com

Send the token as a bearer token in the Authorization header, and the fields as a JSON body with the Content-Type: application/json header.

Step 1: Upload the video and thumbnail

Request a signed URL for each file, then send the bytes to it with a PUT. Both calls take the same bearer token.

cURL

bash

curl -X POST https://api.begenuin.com/api/v3/users/video/upload/create_upload_url \
  -H "Authorization: Bearer {{GN_ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{ "contentType": "video/mp4", "path": "temp_video/{{VIDEO_FILE}}" }'

Response

json

{
  "code": 200,
  "message": "Upload URL generated successfully.",
  "data": { "uploadURL": "https://media-bucket.s3.amazonaws.com/temp_video/{{VIDEO_FILE}}?X-Amz-Signature=..." }
}

cURL

bash

curl -X PUT "{{UPLOAD_URL}}" -H "Content-Type: video/mp4" --data-binary @recap.mp4

Repeat for the thumbnail with "contentType": "image/jpeg" and "path": "uploads/thumbnails/{{THUMB_FILE}}".

Rule	Detail
Paths	Videos go under temp_video/, thumbnails under uploads/thumbnails/. The file name after the folder is what you pass in step 2.
File names	Make each one unique, such as <uuid>_<timestamp>.mp4. A video file name that was posted before is rejected in step 2.
Content types	video/, image/, audio/, and text/. Anything else returns 412 with code 5174.
Expiry	The signed URL is valid for one PUT and a short time. Request it right before the upload, and send the same Content-Type you asked for.

Step 2: Post the video

Parameters

Parameter	Type	Required	Description
chat_id	string	Required	UUID of the group, from Create a group in a community.
video_name	string	Required	The file name uploaded under temp_video/.
thumbnail_name	string	Required	The file name uploaded under uploads/thumbnails/.
aspect_ratio	string	Required	Such as "9:16".
duration	string	Required	Length in seconds, such as "8".
resolution	string	Required	Such as "1080x1920".
size	string	Required	File size, such as "5MB".
description_text	string	Optional	Caption, up to 2,000 UTF-16 code units. Requires description_data.
description_data	string	Required with description_text	JSON string of the caption split into text and mentions: ["Hi, this is ", {"user_id": "<uuid>"}, " in ", {"community_id": "<uuid>"}].
questions	array of strings	Optional	Ids of questions to attach, so members answer them in replies.
link	string	Optional	A URL shown with the video. Can't be combined with linkouts.
linkouts	array	Optional	One or more link-out cards. See Link-outs.
meta_data	object	Optional	Free-form, such as {"topic": "Race day"}.
message_id	string	Optional	A UUIDv4 to use as the post's id. A reused id is rejected.
source	string	Optional	Where the file came from: device, youtube, tiktok, instagram, or ai.
is_ai_generated	boolean	Optional	Marks the post as AI-generated.
ingestion_source	integer	Optional	1 uploads, 2 Clip It, 3 social import. Allowed only with is_ai_generated or is_ai_generated_video.
video_path, thumbnail_path, is_ai_generated_video, is_ai_generated_thumbnail	string, boolean	Optional	For media produced by Genuin's generation flow: the source folders in the generation bucket, and the flags that copy them into place.
platform	string	Optional	mobile or web, used to validate link-out URLs.
language	string	Optional	Two-letter code, such as en.
location	object	Optional	{"latitude", "longitude", "id", "name"}, all required when sent.
brand_context	array	Optional	[{"type": "...", "id": "..."}] entries that tie the post to brand objects.

Link-outs

A link-out is a card on the video that opens a URL. Each entry in linkouts has an optional style (integer), cta_text, cta_link, cta_metadata, and a required links array with at least one link:

Field	Type	Required	Description
position	integer	Required	Order of the link in the card.
link	string	Required	The URL. Genuin validates it against your brand's allowed domains and returns 412 with the failing URLs when one is rejected.
image	string	Optional	File name of a card image uploaded to Genuin's media storage.
title	string	Optional	Card title.
cta_text	string	Optional	Button label, 1 to 24 characters.
metadata	object	Optional	Free-form.

Request

cURL

bash

curl -X POST https://api.begenuin.com/api/thirdparty/users/conversation/reply \
  -H "Authorization: Bearer {{GN_ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "{{CHAT_ID}}",
    "video_name": "{{VIDEO_FILE}}",
    "thumbnail_name": "{{THUMB_FILE}}",
    "aspect_ratio": "9:16",
    "duration": "8",
    "resolution": "1080x1920",
    "size": "5MB",
    "description_text": "Finish line at the Ridge 50K",
    "description_data": "[\"Finish line at the Ridge 50K\"]"
  }'

Returns

Returns 200 OK with the group card and the new post in chats. The post is visible in the group feed as soon as the response arrives.

Response

json

{
  "code": 200,
  "message": "Reply Sent Successfully",
  "data": {
    "chat_id": "1a14b9e2-9552-48d5-b1e3-a1ba237891cf",
    "type": 4,
    "no_of_views": 0,
    "settings": { "discoverable": true },
    "share_url": "https://community.example.com/community/trail-runners/race-recaps",
    "is_offline": false,
    "group": { "group_id": "f67c89d0-9abc-4abc-bdef-56789abcf456", "group_name": "Race recaps" },
    "brand_id": 1429,
    "is_subscriber": false,
    "member_info": { "status": 1, "role": 1 },
    "chats": [
      {
        "owner": { "member_id": "0bf977ed-4887-4056-a8f4-1f0de71101f1", "nickname": "examplebrand" },
        "user_id": "0bf977ed-4887-4056-a8f4-1f0de71101f1",
        "thumbnail_url": "https://media.begenuin.com/uploads/thumbnails/{{THUMB_FILE}}",
        "video_url": "https://media.begenuin.com/temp_video/{{VIDEO_FILE}}",
        "link": null,
        "duration": "8",
        "size": "5MB",
        "aspect_ratio": "9:16",
        "resolution": "1080x1920",
        "conversation_id": "a5006e51-8950-4e1f-9b9a-65714720b0a6",
        "conversation_at": 1760543999000,
        "is_read": true,
        "is_reply": false,
        "questions": [],
        "meta_data": {},
        "no_of_views": 0,
        "no_of_comments": 0,
        "share_url": "https://community.example.com/v/finish-line-at-the-ridge-50k?l=11d88992ba811475"
      }
    ]
  }
}

chats[0].conversation_id is the post's id, and chats[0].share_url is its public link. video_url and thumbnail_url are the CDN URLs of the files you uploaded.

Errors

Every error response carries an HTTP status, a string code, a message, and a data object. Match on code.

HTTP status	code	Cause	Fix
400 Bad Request	none	A field failed validation, such as a chat_id that isn't a UUID. The body is {"data": {}} with no code or message.	Check the Parameters table.
403 Forbidden	5230	The group's "who can post" setting excludes the token's account. Message: XXXX-[Access Denied]..	Post from a group member, or change the setting with Update a group and its members.
403 Forbidden	5243	The group belongs to a brand outside your network.	Use a group under your brand.
404 Not Found	5044	The group doesn't exist or is deleted.	Check chat_id.
404 Not Found	5235	Link-out validation needs the brand, and it isn't active.	Contact the Genuin team.
409 Conflict	5057	video_name or message_id was posted before. Message: You have already replied to this video..	Upload under a new file name, and use a new message_id.
412 Precondition Failed	5166	A link-out URL isn't allowed. data.err_msg lists each URL with the reason.	Use URLs on your brand's allowed domains.
412 Precondition Failed	5174	Step 1 was called with a content type outside video, image, audio, or text.	Send a supported contentType.
422 Unprocessable Entity	5023	Step 1 couldn't sign the URL. Message: Could not fetch credentials..	Retry. If it persists, contact the Genuin team.
422 Unprocessable Entity	5059	The post couldn't be saved. Message: Error in sending reply..	Retry once. If it persists, contact the Genuin team with the request timestamp.

Limitations

One post per file: A video_name can be posted once. Upload again under a new name to post the same clip twice.
No edit or delete: There's no third-party endpoint to change or remove a post. Use Brand Control Center under Curate.
Rate limit: There's no rate limit on this endpoint or the signed-URL endpoint.

Post a video to a group

Endpoint

Step 1: Upload the video and thumbnail

Step 2: Post the video

Parameters

Link-outs

Request

Returns

Response

Errors

Limitations

See also

Related articles