Privacy

Export or erase everything held about one person, and how long message content is kept.

Export the data of one person

GET/v1/privacy/contact

Export everything held about one person (data-subject access request): consent and its history, contacts, messages (up to 5 000), inbox, assignments, blast participation, scheduled and recurring messages, satisfaction answers. Account owner or API key only.

Query parameters

phonestringrequired
International format +<country code><number>

Responses

200Everything held for that number
Response fields
- exported_atstringrequired
- phonestringrequired
- consentany
- consent_historyarray of anyrequired
- contactsarray of anyrequired
- messagesarray of anyrequired
- messages_truncatedbooleanrequired
- inboxarray of anyrequired
- chat_metadataarray of anyrequired
- assignmentsarray of anyrequired
- blast_participationarray of anyrequired
- scheduled_messagesarray of anyrequired
- recurring_messagesarray of anyrequired
- csat_responsesarray of anyrequired
400INVALID_NUMBER

Request

curl "https://api.chatkomodo.com/v1/privacy/contact?phone=%2B447700900123" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"

const res = await fetch('https://api.chatkomodo.com/v1/privacy/contact?phone=%2B447700900123', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);

import os
import requests

res = requests.get(
    "https://api.chatkomodo.com/v1/privacy/contact?phone=%2B447700900123",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('GET', 'https://api.chatkomodo.com/v1/privacy/contact?phone=%2B447700900123', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

print_r(json_decode((string) $res->getBody(), true));

Response 200

{
  "exported_at": "string",
  "phone": "+447700900123",
  "consent": "string",
  "consent_history": [
    "string"
  ],
  "contacts": [
    "string"
  ],
  "messages": [
    "Hi Sam, your order has shipped."
  ],
  "messages_truncated": true,
  "inbox": [
    "string"
  ],
  "chat_metadata": [
    "string"
  ],
  "assignments": [
    "string"
  ],
  "blast_participation": [
    "string"
  ],
  "scheduled_messages": [
    "Hi Sam, your order has shipped."
  ],
  "recurring_messages": [
    "Hi Sam, your order has shipped."
  ],
  "csat_responses": [
    "string"
  ]
}

Erase the data of one person

DEL/v1/privacy/contact

Erase everything held about one person (right to erasure). Irreversible. confirm must repeat the phone number, otherwise the call fails with 400 CONFIRMATION_REQUIRED. By default an opt-out record is kept so the person is not messaged again (keep_suppression: false removes it too). Account owner or API key only.

Request body

phonestringrequired
confirmstringrequired
The same phone number again
keep_suppressionboolean
Default true

Responses

200Erased
Response fields
- okbooleanrequired
- deletedobjectrequired
  Rows removed per data type
- suppression_keptbooleanrequired
- failedarray of stringrequired
  Data types that could not be erased; empty when the erasure is complete
400INVALID_NUMBER or CONFIRMATION_REQUIRED
500ERASURE_INCOMPLETE: some records could not be deleted (failed lists them); repeat the request or contact support

Request

curl -X DELETE "https://api.chatkomodo.com/v1/privacy/contact" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+447700900123",
  "confirm": "+447700900123",
  "keep_suppression": true
}'

const res = await fetch('https://api.chatkomodo.com/v1/privacy/contact', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phone": "+447700900123",
    "confirm": "+447700900123",
    "keep_suppression": true
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);

import os
import requests

res = requests.delete(
    "https://api.chatkomodo.com/v1/privacy/contact",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "phone": "+447700900123",
        "confirm": "+447700900123",
        "keep_suppression": True,
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('DELETE', 'https://api.chatkomodo.com/v1/privacy/contact', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'phone' => '+447700900123',
        'confirm' => '+447700900123',
        'keep_suppression' => true,
    ],
]);

print_r(json_decode((string) $res->getBody(), true));

Response 200

{
  "ok": true,
  "deleted": {},
  "suppression_kept": true,
  "failed": [
    "string"
  ]
}

Get the message retention

GET/v1/privacy/retention

How long message content is kept.

Responses

200Retention
Response fields
- message_daysinteger | nullrequired
  Your own setting; null = platform default
- effective_daysintegerrequired
- default_daysintegerrequired
- min_daysintegerrequired
- max_daysintegerrequired

Request

curl "https://api.chatkomodo.com/v1/privacy/retention" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY"

const res = await fetch('https://api.chatkomodo.com/v1/privacy/retention', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);

import os
import requests

res = requests.get(
    "https://api.chatkomodo.com/v1/privacy/retention",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('GET', 'https://api.chatkomodo.com/v1/privacy/retention', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
]);

print_r(json_decode((string) $res->getBody(), true));

Response 200

{
  "message_days": 1,
  "effective_days": 1,
  "default_days": 1,
  "min_days": 1,
  "max_days": 1
}

Set the message retention

PUT/v1/privacy/retention

Set the message retention period in days (between min_days and max_days), or null for the platform default. Account owner only.

Request body

message_daysinteger | nullrequired

Responses

200Saved
Response fields
- message_daysinteger | nullrequired
- effective_daysintegerrequired
400Out of range (VALIDATION_FAILED)

Request

curl -X PUT "https://api.chatkomodo.com/v1/privacy/retention" \
  -H "Authorization: Bearer $CHATKOMODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message_days": 90
}'

const res = await fetch('https://api.chatkomodo.com/v1/privacy/retention', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CHATKOMODO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "message_days": 90
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
console.log(data);

import os
import requests

res = requests.put(
    "https://api.chatkomodo.com/v1/privacy/retention",
    headers={
        "Authorization": f"Bearer {os.environ['CHATKOMODO_API_KEY']}",
    },
    json={
        "message_days": 90,
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->request('PUT', 'https://api.chatkomodo.com/v1/privacy/retention', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('CHATKOMODO_API_KEY'),
    ],
    'json' => [
        'message_days' => 90,
    ],
]);

print_r(json_decode((string) $res->getBody(), true));

Response 200

{
  "message_days": 1,
  "effective_days": 1
}