API Reference/Messaging/Start a new chat

Start a new chat

POSThttps://api.postpress.ai/v1/chats

Start a new conversation with one or more attendees. The body is sent as `multipart/form-data` so you can attach files alongside the textual fields.

LinkedIn-specific parameters use bracket notation in form data, for example linkedin[api]=classic and linkedin[inmail]=true. Some interactive clients render the nested object incorrectly in generated snippets.

Authorization

X-API-KEYstringrequired
API key from your postpress dashboard. Sent as a request header.

Request body

Encoded as multipart/form-data.

account_idstringlength ≥ 1required
The postpress account that will send the first message.
attendees_idsarray of stringsrequired
One or more attendee provider IDs. For Instagram use `provider_messaging_id`. For LinkedIn users, use a `provider_id` starting with `ACo` (classic), `ACw` (Sales Navigator) or `AE` (Recruiter). For LinkedIn company messaging use `messaging_id`. For WhatsApp use `00000000@s.whatsapp.net`.
attendees_ids array
<provider_id>string
textstring
The first message that will start the conversation. LinkedIn Recruiter supports a limited HTML subset: `<strong>`, `<em>`, `<a href="...">`, `<ul>`, `<ol>`, `<li>` (nestable).
subjectstring
Optional subject for the conversation.
attachmentsarray of binaries
Files attached to the first message.
attachments array
<file>binary
voice_messagebinary
(LinkedIn / WhatsApp) File to send as a voice message. WhatsApp prefers `.mp3` or `.m4a`; LinkedIn prefers `.m4a`. For Instagram and Telegram, send it via `attachments` instead.
video_messagebinary
(LinkedIn) File to send as a video message. On WhatsApp send videos via `attachments` instead.
linkedinobject
LinkedIn-specific options. Pick one of the three variants below based on the LinkedIn API you want to use.
linkedin object
Classic optionsobject
Use `api: "classic"` (default). Fields specific to LinkedIn classic.
Classic options object
apistringclassic
LinkedIn API to use. Defaults to `classic`.
topicstring
service_requestrequest_demosupportcareersother
Mandatory when starting a conversation with a company.
applicant_idstring
Mandatory to start a conversation with a job applicant. Fetch via the job postings endpoints.
invitation_idstring
Mandatory to message a user from whom you received a still-pending invitation.
inmailboolean
When `true`, start the conversation with an InMail.
Recruiter optionsobject
Use `api: "recruiter"`. Fields specific to LinkedIn Recruiter.
Recruiter options object
apistringrecruiterrequired
signaturestring
Signature of the sender.
hiring_project_idstring
ID of the project the chat should be started in.
job_posting_idstring
Related job posting id for initial outreach to a candidate.
sourcing_channelstring
JOB_POSTING_RECOMMENDED_MATCHESJOB_POSTINGREFERRALINTERNAL_CANDIDATESAUTOMATED_SOURCINGRECRUITER_SEARCHCAREER_SITE
Sourcing channel of the project used to start a Recruiter conversation.
email_addressstring
Recipient email when the chat should be started by email rather than InMail.
visibilitystring
PUBLICPRIVATEPROJECT
Visibility within your organization. Defaults to `PRIVATE`.
follow_upobject
Schedule a follow-up message. Available for Recruiter PRO account owners only.
follow_up object
subjectstringrequired
Subject for the follow-up message.
textstringrequired
Textual content for the follow-up message.
attachmentsarray of binaries
Optional attachments for the follow-up message.
attachments array
<file>binary
scheduled_timeobjectrequired
When the follow-up should be sent. Provide either a `days` window or a `weeks` window, with a timezone.
scheduled_time object
Days basedobject
Schedule by a number of days (3 – 28).
Days based object
daysnumberrequired
Number of days from now to send the follow-up. Min 3, max 28.
timezonestringrequired
IANA timezone, e.g. `Europe/Paris`, `America/Phoenix`.
Weeks basedobject
Schedule by a number of weeks (1 – 4).
Weeks based object
weeksnumberrequired
Number of weeks from now to send the follow-up. Min 1, max 4.
timezonestringrequired
IANA timezone, e.g. `Europe/Paris`, `America/Phoenix`.
Sales Navigator optionsobject
Use `api: "sales_navigator"`. No additional fields beyond `api`.
Sales Navigator options object
apistringsales_navigatorrequired

Response 201 Created

objectstringChatStartedrequired
chat_idstringrequired
The postpress id of the newly started chat. Nullable when the provider does not return an id immediately.
message_idstringrequired
The postpress id of the first message. Nullable when the provider does not return an id immediately.

Example request

curl --request POST \
  --url 'https://api.postpress.ai/api/v1/chats' \
  --header 'X-API-KEY: pp_live_...' \
  --header 'accept: application/json' \
  --header 'content-type: multipart/form-data' \
  --form 'account_id=acc_01HXYZ4QK3WJ8FN3M6QH7TZ8GR' \
  --form 'attendees_ids[]=ACoAACr-1eYBl...' \
  --form 'text=Hey! Interested in chatting about your role.' \
  --form 'linkedin[api]=classic' \
  --form 'linkedin[inmail]=true'

Example response

{
  "object": "ChatStarted",
  "chat_id": "chat_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
  "message_id": "msg_01HXYZ4QK3WJ8FN3M6QH7TZ8GR"
}

Errors

Every error response follows the same envelope:

titlestringrequired
Short error title.
detailstringoptional
Human-readable explanation.
instancestringoptional
Request identifier for support.
typestringrequired
Error type identifier.
statusnumberrequired
HTTP status code.
400 Bad Request8 types

The request payload is invalid or missing required fields.

  • errors/invalid_parameters - One or more request parameters are invalid or missing.
  • errors/missing_parameters - One or more request parameters are missing.
  • errors/malformed_request - The given request has been rejected by the provider.
  • errors/content_too_large - The request payload is too large for the provider.
  • errors/invalid_url - A url in the payload is invalid.
  • errors/too_many_characters - The provided content exceeds the character limit.
  • errors/unescaped_characters - The request path contains unescaped characters.
  • errors/limit_too_high - Pagination limit too high. See API reference for details.
401 Unauthorized13 types

Credentials are missing, expired, or otherwise invalid.

  • errors/missing_credentials - Some credentials are necessary to perform the request.
  • errors/multiple_sessions - LinkedIn limits multiple sessions on certain Recruiter accounts. Use the cookie connection method.
  • errors/invalid_checkpoint_solution - The checkpoint resolution did not pass successfully. Retry.
  • errors/invalid_proxy_credentials - The provided proxy credentials are invalid.
  • errors/checkpoint_error - The checkpoint does not appear to be resolvable.
  • errors/invalid_credentials - The provided credentials are invalid.
  • errors/expired_credentials - Credentials have expired. Reconnect the account.
  • errors/insufficient_privileges - This resource is out of your API-key scopes.
  • errors/disconnected_account - The account is disconnected from the provider service.
  • errors/disconnected_feature - The service you're trying to reach is disconnected.
  • errors/invalid_credentials_but_valid_account_imap - IMAP/SMTP credentials are invalid but the account is otherwise valid.
  • errors/expired_link - This link has expired. Generate a new one.
  • errors/wrong_account - The provided credentials do not match the correct account.
403 Forbidden9 types

Authenticated but the account is restricted or the action is not allowed.

  • errors/account_restricted - The account has been restricted by the provider.
  • errors/account_mismatch - This action cannot be done with your account.
  • errors/insufficient_permissions - Valid authentication but insufficient permissions to perform the request.
  • errors/session_mismatch - Token user id does not match client session id.
  • errors/feature_not_subscribed - The requested feature has not been subscribed or authenticated properly.
  • errors/subscription_required - A subscription is required to use this feature.
  • errors/unknown_authentication_context - An additional step seems necessary to complete login.
  • errors/action_required - An additional step is required. Complete authentication on the provider's native application.
  • errors/resource_access_restricted - You don't have access to this resource.
404 Not Found2 types

One of the referenced resources does not exist.

  • errors/resource_not_found - The requested resource was not found.
  • errors/invalid_resource_identifier - The provided identifier is not valid.
415 Unsupported Media Type1 types

An attachment or voice/video message was rejected by the provider.

  • errors/unsupported_media_type - The media has been rejected by the provider.
422 Unprocessable Entity35 types

The provider refused to start the chat for a domain-specific reason.

  • errors/invalid_account - The account is not valid for this operation.
  • errors/invalid_recipient - The recipient is not valid.
  • errors/no_connection_with_recipient - The recipient is not a first-degree connection.
  • errors/blocked_recipient - The recipient has blocked this account.
  • errors/user_unreachable - The user cannot be reached.
  • errors/unprocessable_entity - The request cannot be processed.
  • errors/payment_error - A payment is required and could not be completed.
  • errors/action_already_performed - This action has already been performed.
  • errors/invalid_message - The message is invalid.
  • errors/invalid_post - The referenced post is invalid.
  • errors/not_allowed_inmail - InMail is not allowed for this recipient or account.
  • errors/insufficient_credits - Not enough InMail credits.
  • errors/cannot_resend_yet - The message cannot be resent yet.
  • errors/cannot_resend_within_24hrs - The message cannot be resent within 24 hours.
  • errors/limit_exceeded - A provider-side limit has been exceeded.
  • errors/already_invited_recently - The recipient was already invited recently.
  • errors/already_connected - Already connected to this recipient.
  • errors/cannot_invite_attendee - The attendee cannot be invited.
  • errors/parent_mail_not_found - The parent mail was not found.
  • errors/parent_mail_invalid_provider_id - The parent mail provider id is invalid.
  • errors/invalid_reply_subject - Reply subject is invalid.
  • errors/invalid_headers - Headers are invalid.
  • errors/send_as_denied - Send-as permission denied.
  • errors/invalid_folder - Folder is invalid.
  • errors/invalid_thread - Thread is invalid.
  • errors/unauthorized - Unauthorized.
  • errors/sender_rejected - Sender rejected by upstream.
  • errors/recipient_rejected - Recipient rejected by upstream.
  • errors/ip_rejected_by_server - Server rejected the source IP.
  • errors/provider_unreachable - Provider unreachable.
  • errors/account_configuration_error - Account configuration error.
  • errors/cant_send_message - The message cannot be sent.
  • errors/realtime_client_not_initialized - Realtime client not initialized.
  • errors/comments_disabled - Comments are disabled.
  • errors/insufficient_job_slot - No job slot available.
429 Too Many Requests1 types

Rate limited by the upstream provider.

  • errors/too_many_requests - The provider cannot accept any more requests at the moment. Retry later.
500 Internal Server Error3 types

Something went wrong on our side or with the upstream provider.

  • errors/unexpected_error - Something went wrong.
  • errors/provider_error - The provider is experiencing operational problems. Retry later.
  • errors/authentication_intent_error - The current authentication intent was killed after failure.
501 Not Implemented1 types

The requested feature is planned but not yet implemented for this provider.

  • errors/feature_not_implemented - Requested feature is planned but has not been implemented yet.
503 Service Unavailable5 types

postpress is temporarily unable to handle the request.

  • errors/no_client_session - No client session is currently running.
  • errors/no_channel - No channel to client session.
  • errors/no_handler - Handler missing for that request.
  • errors/network_down - Network is down on the server side. Retry shortly.
  • errors/service_unavailable - Service temporarily unavailable. Retry later.
504 Gateway Timeout1 types

The upstream provider did not respond in time.

  • errors/request_timeout - Request timed out. Retry, and contact support if it persists.
Updated May 2026