Reply to content

Use replies when your application receives a content.* event and needs to respond on the provider, such as replying to a comment or message.

How it works

1. Receive and verify the Koil event from Subscribe to events.

2. Store the event id for dedupe, then read the identifiers from the event:

   • metadata.connectedProfileId
   • data.contentType
   • data.externalId

3. Check whether replies are supported for that content type. GET /v1/connected-profiles/{connectedProfileId}/capabilities

4. Submit a reply Publish Request using the event's metadata.connectedProfileId and data.externalId. POST /v1/publish-requests

5. Store the returned publish request ID and status URL.

6. Read status until the reply is completed, failed, or canceled. GET /v1/publish-requests/{publishRequestId}

Example

curl -X POST "https://api.koil.co/v1/publish-requests" \  -H "Authorization: Bearer $KOIL_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: $(uuidgen)" \  -d '{  "publishRequests": [    {      "contentType": "instagram.media.comments",      "connectedProfileId": "cp_123",      "clientItemId": "reply-comment-456",      "args": {        "target": {          "contentType": "instagram.media.comments",          "externalId": "comment_456"        },        "text": "Thanks for reaching out."      }    }  ]}'

Derive the Idempotency-Key from the event id (for example reply-{id}) rather than generating a fresh one, so a redelivered event produces the same reply request instead of a second reply.

The target is the content the publish attaches to, identified exactly as the event identified it — pass the event's contentType and externalId straight through. Targeting a comment publishes a reply; targeting a media item publishes a top-level comment.

DM replies use the same submission flow with contentType: "instagram.dm.messages", but are addressed to a person rather than targeting content: set args.recipientExternalId to the DM event's author.id (or a participant id from instagram.dm.threads reads). Message platforms have no reply-to-message concept on their send APIs — a reply is simply the next message to that person — so Koil's contract reflects that rather than inventing a target the provider cannot honor.

Dedupe and retries

Use the connectedProfileId from the event unless your product intentionally lets an operator choose another eligible Connected Profile.

Events can be retried or replayed. Dedupe inbound events on the event id (also sent as the x-koil-event-id header), and send an Idempotency-Key header when submitting the reply so customer-side retries do not create duplicate replies.

Koil delivers both sides of a conversation: content the connected profile itself authored — an agent replying from the provider's app, or a reply you published through Koil — arrives as a normal content.* event. It is identifiable in-event: the profile's own content has data.author.id === metadata.providerProfileExternalId. Inbox products should render these; automations that respond to events must skip them so a bot never replies to its own replies.

If your reply UI needs fresh provider state, fetch the content before replying: GET /v1/content/{contentType}/{externalId}?connectedProfileId={connectedProfileId}