> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de integração

> Este guia aborda os conceitos-chave necessários para integrar os endpoints de gerenciamento de Mensagens Diretas. Referência para o nível standard da API do X v2 cobrindo gerenciamento.

export const Button = ({href, children}) => {
  return <div className="not-prose">
    <a href={href}>
      <button className="x-btn">
        <span>{children}</span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

Este guia aborda os conceitos-chave necessários para integrar os endpoints de gerenciamento de Mensagens Diretas em sua aplicação.

***

## Autenticação

Os endpoints de DM exigem autenticação de usuário:

| Método                                                                                                                         | Descrição      |
| :----------------------------------------------------------------------------------------------------------------------------- | :------------- |
| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Recomendado    |
| [OAuth 1.0a User Context](/resources/fundamentals/authentication)                                                              | Suporte legado |

<Warning>
  A autenticação App-Only não é suportada. Todas as Mensagens Diretas são privadas.
</Warning>

### Escopos necessários (OAuth 2.0)

| Escopo       | Necessário para            |
| :----------- | :------------------------- |
| `dm.write`   | Enviar e excluir mensagens |
| `dm.read`    | Necessário com dm.write    |
| `tweet.read` | Necessário com escopos dm  |
| `users.read` | Necessário com escopos dm  |

***

## Visão geral dos endpoints

| Método | Endpoint                                            | Descrição                     |
| :----- | :-------------------------------------------------- | :---------------------------- |
| POST   | `/2/dm_conversations/with/:participant_id/messages` | Enviar mensagem individual    |
| POST   | `/2/dm_conversations`                               | Criar conversa em grupo       |
| POST   | `/2/dm_conversations/:dm_conversation_id/messages`  | Adicionar mensagem à conversa |
| DELETE | `/2/dm_events/:event_id`                            | Excluir uma mensagem          |

***

## Enviando mensagens

### Mensagem individual

Envie uma mensagem para um usuário específico. Cria uma nova conversa se ainda não existir:

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/dm_conversations/with/9876543210/messages" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"text": "Hello!"}'
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Send a one-to-one DM
  response = client.dm_conversations.create_message(
      participant_id="9876543210",
      text="Hello!"
  )
  print(response.data)
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Send a one-to-one DM
  const response = await client.dmConversations.createMessage({
    participantId: "9876543210",
    text: "Hello!",
  });
  console.log(response.data);
  ```
</CodeGroup>

### Conversa em grupo

Crie um novo grupo e envie a primeira mensagem:

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/dm_conversations" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation_type": "Group",
      "participant_ids": ["944480690", "906948460078698496"],
      "message": {"text": "Welcome to our group!"}
    }'
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Create a group conversation
  response = client.dm_conversations.create(
      conversation_type="Group",
      participant_ids=["944480690", "906948460078698496"],
      message={"text": "Welcome to our group!"}
  )
  print(response.data)
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Create a group conversation
  const response = await client.dmConversations.create({
    conversationType: "Group",
    participantIds: ["944480690", "906948460078698496"],
    message: { text: "Welcome to our group!" },
  });
  console.log(response.data);
  ```
</CodeGroup>

<Note>
  O campo `conversation_type` deve ser definido como `"Group"` (diferencia maiúsculas de minúsculas).
</Note>

### Adicionar a uma conversa existente

Envie uma mensagem para qualquer conversa da qual você faça parte:

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl -X POST "https://api.x.com/2/dm_conversations/1582103724607971328/messages" \
    -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"text": "Another message"}'
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

  # Add message to existing conversation
  response = client.dm_conversations.add_message(
      dm_conversation_id="1582103724607971328",
      text="Another message"
  )
  print(response.data)
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

  // Add message to existing conversation
  const response = await client.dmConversations.addMessage({
    dmConversationId: "1582103724607971328",
    text: "Another message",
  });
  console.log(response.data);
  ```
</CodeGroup>

***

## Anexos de mídia

Anexe uma peça de mídia (foto, vídeo ou GIF) por mensagem.

<Steps>
  <Step title="Faça upload da mídia">
    Use o [endpoint de Media Upload](/x-api/media/quickstart/media-upload-chunked) para enviar seu arquivo e obter um `media_id`.
  </Step>

  <Step title="Inclua na mensagem">
    ```json theme={null}
    {
      "text": "Check out this image!",
      "attachments": [{"media_id": "1583157113245011970"}]
    }
    ```
  </Step>
</Steps>

<Note>
  * O usuário autenticado deve ter enviado a mídia
  * A mídia fica disponível por 24 horas após o upload
  * Apenas um anexo por mensagem é suportado
</Note>

***

## Compartilhando posts

Inclua um Post na sua mensagem adicionando a URL do Post ao texto:

```json theme={null}
{
  "text": "Have you seen this? https://x.com/XDevelopers/status/1580559079470145536"
}
```

A resposta incluirá um campo `referenced_tweets` com o ID do Post.

***

## Requisitos da mensagem

| Field         | Obrigatório | Observações                      |
| :------------ | :---------- | :------------------------------- |
| `text`        | Sim\*       | Obrigatório se não houver anexos |
| `attachments` | Sim\*       | Obrigatório se não houver texto  |

\*Pelo menos um entre `text` ou `attachments` deve ser fornecido.

***

## Compatibilidade de IDs com a v1.1

Os IDs de conversa e evento são compartilhados entre os endpoints v1.1 e v2. Isso possibilita fluxos híbridos:

* Criar mensagens com a v2
* Excluir mensagens com a v1.1 (ainda não disponível na v2)
* Referenciar IDs de conversa das URLs do x.com

***

## Tratamento de erros

| Status | Erro              | Solução                                     |
| :----- | :---------------- | :------------------------------------------ |
| 400    | Invalid request   | Verifique o formato do corpo da solicitação |
| 401    | Unauthorized      | Verifique o access token                    |
| 403    | Forbidden         | Verifique escopos e permissões do usuário   |
| 429    | Too Many Requests | Aguarde e tente novamente                   |

### Problemas comuns

<AccordionGroup>
  <Accordion title="Não é possível enviar para o usuário">
    O destinatário pode ter configurações de DM que impedem mensagens de usuários desconhecidos, ou pode tê-lo bloqueado.
  </Accordion>

  <Accordion title="Falha no anexo de mídia">
    Certifique-se de que a mídia foi enviada pelo mesmo usuário autenticado e tem menos de 24 horas.
  </Accordion>

  <Accordion title="Falha na criação do grupo">
    Verifique se todos os IDs de participantes são válidos e se os usuários permitem convites de DM em grupo.
  </Accordion>
</AccordionGroup>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/direct-messages/manage/quickstart" width="24" height="24" data-path="icons/xds/icon-rocket.svg">
    Envie sua primeira Mensagem Direta
  </Card>

  <Card title="Consulta de DM" icon="inbox" href="/x-api/direct-messages/lookup/introduction">
    Recupere conversas de DM
  </Card>

  <Card title="Upload de mídia" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-photo.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=d0986097dcff55478c32801b20440ecc" href="/x-api/media/quickstart/media-upload-chunked" width="24" height="24" data-path="icons/xds/icon-photo.svg">
    Faça upload de mídia para anexos
  </Card>

  <Card title="Referência da API" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/direct-messages/create-dm-message-by-participant-id" width="24" height="24" data-path="icons/xds/icon-code.svg">
    Documentação completa do endpoint
  </Card>
</CardGroup>