Instagram DM integration: connecting, the inbox and removing

When the Instagram DM integration is connected, direct messages sent to your Instagram business account land in the shared Piyzi inbox and your whole team replies from one place. Comments on your posts are a separate Pi Store card — connecting DMs does not bring comments along.

Prerequisites

• A Piyzi account with an active subscription.

• Pi Store edit permission, or being the workspace owner.

• Your Instagram account must be a business (professional) account. Personal accounts cannot be connected.

• You must sign in as an admin of that Instagram account during authorization.

• A Facebook Page is not required. Piyzi uses Instagram Login, so studios and salons with no Facebook Page can still connect.

Connecting the integration

1. In the left menu, open My Business → Pi Store.

2. Under the Messaging heading, click the Instagram DM card.

3. In the dialog that opens, click “Connect with Instagram”. A pop-up window opens.

4. Sign in to Instagram in that window and approve the requested permissions.

5. When you return to Piyzi the card shows “Instagram Connected” together with the connected @username.

Requested permissions

• instagram_business_basic: reads your account's basic information (username, name, profile picture) so the connection can be matched to the right business, and fetches the sender's username, name and profile picture once so the inbox does not show a raw numeric ID.

• instagram_business_manage_messages: receives incoming direct messages, sends your replies, marks conversations as read and sends reactions.

Your followers, your posts, your ad accounts and your comments are not accessed with these permissions. Comments require the separate Instagram Comments card and its own permission.

Using the inbox

After connecting, a Messaging → Inbox entry appears in the left menu for staff who have the messaging permission. The inbox is shared: WhatsApp and Instagram conversations sit in the same list and the channel tabs at the top (All / WhatsApp / Instagram DM) filter it.

Replying to messages

• You cannot start a conversation. Instagram's rules mean a conversation only exists once the customer messages you — there is no “new conversation” button.

• The customer's message opens a 24-hour reply window. Within that window you can reply freely; the remaining time is shown above the composer.

• You can send text, photos, videos and audio. Documents cannot be sent over Instagram DM.

• You can reply to a specific message and react to a message. Instagram accepts a limited set of reactions, so the emoji you pick is mapped to the closest supported one.

• Opening a conversation marks it as read on Instagram as well.

• Replying requires the message sending permission; viewing the inbox only requires the messaging view permission.

Incoming attachments and shares

• Photos, videos and audio are downloaded to Piyzi and shown directly in the bubble.

• A shared post or Reel is labelled “Shared content (Reel/post)”. For a post the thumbnail is downloaded and shown; a Reel arrives as an Instagram link, so the bubble offers to open it on Instagram instead of showing a preview.

• A reply to your story is labelled “Reply to a story”, and being mentioned in a story is labelled “Mention in a story”.

• A file sent by the customer is shown as a document and can be opened — you just cannot send one back.

• Anything Instagram delivers in a form Piyzi cannot render is shown as “Unsupported message type”, so no message is silently lost.

Assigning and closing a conversation

• The Conversation Management panel on the right is internal only: the customer is never notified of anything you do there.

• Select a staff member under “Staff member handling the conversation”. The thread then shows “{name} joined the conversation”.

• Removing the assignment writes “{name} left the conversation”; handing it to someone else writes both events in order.

• Only staff with an active membership in this business can be assigned.

• “Close Conversation” closes it and writes “The conversation was closed by …”. If the same person messages again it opens as a separate conversation — the customer never notices.

• Assignment and closing both require the message sending permission.

Customer matching and the profile picture

• Instagram conversations are matched to a customer by the Instagram username on the customer card. Case and a leading @ do not matter.

• The webhook only carries an account ID, not the username, so Piyzi fetches the profile once and then matches. That is why the very first message may briefly show a numeric ID.

• While a conversation is unmatched, matching is retried on every incoming message — so adding the customer later fixes the older conversation as well.

• “Match with an existing customer” also writes the Instagram username onto the customer card, so later conversations match by themselves.

• “Add as a new customer” writes to your customer database and therefore requires the customer creation permission.

• The profile picture comes from Instagram's CDN and that link expires over time. When it does, the picture stops loading and the initial letter is shown instead — nothing is broken. If the customer card has a photo, that photo is used first.

Notification settings

• The Notification Settings button in the inbox opens the panel; both viewing and changing it require the notification settings permission.

• For every staff member you can toggle WhatsApp, IG Message and IG Comment separately.

• If a conversation is assigned, the notification goes only to the assignee — even if they are not on the list.

• If nothing has been configured yet, only the business owner is notified. If the list exists but is empty, nobody is notified.

• At most one notification is sent per conversation every 2 minutes, and notifications only reach staff who are signed in to the mobile app.

Deleting a conversation

• “Delete Conversation” is a separate permission from closing, because it is permanent and audit-logged.

• The conversation and all of its messages are removed from Piyzi, on every Piyzi device, and this cannot be undone.

• It is deleted on Piyzi's side only. Meta's APIs do not allow deleting the copy in the other person's Instagram app — there is no such option, for anyone.

• If the same person writes again, a clean new conversation opens; the old history does not come back.

Removing the app

1. Open My Business → Pi Store.

2. Click the Instagram DM card.

3. Click “Disconnect”.

• New messages are no longer received and you can no longer send.

• Conversations and messages already in Piyzi stay readable — the integration is deactivated, not erased.

• The Inbox entry disappears from the menu when no messaging channel is left connected.

• Instagram Comments is a separate card: disconnecting DMs does not disconnect comments.

• You can reconnect at any time by following the same steps.

You can also remove the app on Instagram's side, from your account's app settings. Instagram then notifies Piyzi and the integration is deactivated automatically. If you additionally submit a data deletion request to Meta, every Instagram conversation and comment belonging to that account is removed from Piyzi.

Troubleshooting

• The card does not show “Connected”: a pop-up blocker may have interrupted the authorization, or you may have closed the Instagram window before it finished. Try again from Pi Store.

• Authorization fails: make sure the account is a business (professional) account and that you are signing in as an admin of it.

• There is no Inbox in the menu: the integration may be disconnected, or your role may be missing the messaging view permission.

• “Your connection has expired — reconnect via Pi-Store”: the Instagram token is refreshed automatically, but a password change or a revoked permission invalidates it. Incoming messages keep arriving; reconnect from Pi Store to be able to send again.

• You cannot send a reply: the 24-hour window has probably closed. On Instagram there is no template fallback — you can send again once the customer writes to you.

• A conversation shows a number instead of a name: the profile could not be fetched (a private profile, or a temporary Instagram error). The conversation still works; match it to a customer manually.

• The profile picture does not load: the Instagram CDN link has expired. The initial letter is shown instead and no action is needed.

• The customer is not matched: fill in the Instagram username on the customer card, or use “Match with an existing customer” — the username is then saved for next time.