Guides

Your First Integration

Once your endpoints are set up, you can start using our API to enqueue your users' conversations.

Your First Request

We have designed a simple and reliable API for enqueuing your conversations. To receive your first reply, simply follow the steps below.

1. Authentication

We use access keys to authenticate requests made to our API. An access key is required to start sending requests. To create one, visit your customer dashboard under "Project > Access Keys" section.

Once you have your access key, include it in every request using the HTTP header Authorization like this Bearer {api-key} (e.g. Authorization: Bearer sk-proj-XXXXXXXXXX).

2. Request Parameters

Conversation enqueue endpoint requires the following parameters:

Name	Description
`userProfileId`	Your user/customer profile ID, used to retrieve data from your Profile Endpoint.
`personaProfileId`	Your persona/virtual profile ID, used to retrieve data from your Profile Endpoint.
`language`	The desired language for your answer. For today's example, we are going to use `EN` (english).

3. Building Your Request Body

Our API expects a request containing JSON. Below is an example of the expected format:

{
  "userProfileId": "YOUR_USER_PROFILE_ID",
  "personaProfileId": "YOUR_PERSONA_PROFILE_ID",
  "language": "EN"
}

4. Sending Your Request

You have to send a request using a cURL command.

curl -X POST https://api.dumgum.com/cs/v1/content_creation/conversations/enqueue \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $YOUR_ACCESS_KEY" \
-d '{
  "userProfileId": "1234",
  "personaProfileId": "9876",
  "language": "EN"
}'

You should receive a 204 HTTP response status, indicating that your request has been accepted. An answer will be sent soon to your Incoming Content Endpoint.

5. Receiving Your Reply

You will receive a reply as soon as possible. If the user replies again, simply enqueue the conversation again, and we'll continue from there!

Before You Go Live

A short checklist of profile details that are easy to forget but materially affect conversation quality. All are returned by your Profile Endpoint; see the Profile data type for the full schema.

Field	Why it matters
`timeZone`	Sets the Persona's sense of the local time of day. Set it on the persona profile. If omitted, the Persona falls back to UTC and references the wrong time (e.g. "who's chatting at 4am?" when it's 6am for the user). Use an IANA name like `Europe/Paris`.
`countryCode`	Required for `city` and `postalCode` to be used at all. Without a two-letter ISO 3166-1 code, both are ignored.
Public image URLs	We never download or store images, so every `mainPictureUrl`, `pictures`, and `privatePictures` URL must be HTTPS and publicly reachable when content is generated.
`firstName` or `nickname`	At least one is required on every profile.
`version`	Bump it whenever your profile data changes so we refresh our cached copy; otherwise updates won't be picked up until `expiresAt`.